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(54) TiUe: HYPERMEDIA OBJECT MANAGEMENT 

(57) Abstract 

A method and apparatus that uses a hyper- 
media approach to managing distributed objects. 
A first embodiment of the present invention uses 
the World Wide Web hypcmicdia system. A 
user initializes browser software that allows the 
user to browse and change various attributes of 
objects in the system. The browser communi- 
cates with a server that includes an http adapter 
and a gateway. The gateway can access ob- 
jects in the system and generate HTML code 
in accordance with the objects. One embodi- 
ment of the present invention uses hierarchical 
trcc-orientcd objects. These objects arc "self- 
describing" (also called "introspective"). The 
server queries the objects in response to the 
queries from the browser and each queried ob- 
ject responds with information about itself. In 
another preferred embodiment, the server initi- 
ates queries of the objects and retains this in- 
formation for use in responding to later queries 
from the browser. 
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HYPERMEDIA OBJECT MANAGEMENT 

HELD OF THE INVENTION 

This application relates to object oriented programming and, in 
particular, to management of distributed objects via the World Wide Web. 

BACKGROUND OF THE INVENTION 

The past several years have seen an explosive growth of the use of 
distributed objects. Now, a single system may be composed of objects 
obtained from different vendors and having different interfaces. Such objects 
are called "heterogeneous objects." Thus, a system can be formed of a large 
and rapidly changing number of heterogeneous objects. Such a system 
requires a flexible and adaptive approach for system and application 
management- Conventionally, a heterogeneous system is managed by way of 
object-specific presentation facilities, i.e., by way of a user front-end that was 
written for each type of heterogeneous object. Such an approach Is, however, 
too expensive in both development time and maintenance and administrative 
costs. In addition, conventional object management is often achieved through 
a single management center. Use of a single center is not efficient when a 
large number of objects need to be managed. 
SUMMARY OF THE INVENTION 

The present invention overcomes the problems and disadvantages of 
the prior art by using a hypermedia approach to object management. In this 
approach, each object is akin to a hypermedia document. The described 
embodiment of the present invention uses the World Wide Web hypermedia 
system. In a preferred embodiment of the present invention, a user initializes 
browser software that allows the user to browse and change various attributes 
of objects in the system. The browser communicates with a server that 
includes an http adapter and a gateway. The gateway can access objects in 
the system and generate HTML code in accordance with the objects. 

A described embodiment of the present invention uses hierarchical tree- 
oriented objects. In a first embodiment, these objects are "self-describing" 
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(also called "introspective"). The server queries the objects in response to the 
queries from the browser and each queried object responds with information 
about itself. In another preferred embodiment, the server initiates queries of 
the objects and retains this information for use in responding to later queries 
from the browser. 

In accordance with the purpose of the invention, as embodied and 
broadly described herein the invention is a system for managing objects, 
including a first server, comprising: a first receiver portion configured to 
receive a request in a hypermedia format; a first translator portion configured to 
convert the hypermedia request to an object request;a sender portion 
configured to send the object request to an object manager; a second receiver 
portion configured to receive a response from the object manager; and a 
second translator portion configured to convert the object manager response to 
the hypermedia format. 

In further accordance with the purpose of this invention, as embodied 
and broadly described herein the invention is a method for browsing objects, 
where a browser communicates with a server, comprising the steps, performed 
by the browser, of: sending an initial URL to the server; receiving first data 
frorh the server, where the first data specifies an object corresponding to the 
URL; sending user-entered data associated with the object to the server; and 
receiving second data from the server, where the second data specifies a 
second object corresponding to the user-entered data. 

Advantages of the invention will be set forth in part in the description 
which follows and in part will be obvious from the description or may be 
learned by practice of the invention. The advantages of the invention will be 
realized and attained by means of the elements and combinations particularly 
pointed out in the appended claims and equivalents. 
BRIEF DESCRIPTION OF THE DRAWINGS^ 

The accompanying drawings, which are incorporated in and constitute 
a part of this specification, illustrate several embodiments of the invention and, 
together with the description, serve to explain the principles of the invention. 
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Fig. 1 is a block diagram of a computer system in accordance with a 
preferred embodiment of the present invention. 

Fig. 2 is another block diagram of a computer system in accordance 
with a preferred embodiment of the present invention. 

Fig. 3 is a diagram of data sent between a browser, server, and object 
manager in accordance with the embodiment of Fig, 1 . 

Fig. 4 is a diagram of a format in which objects are organized. 
Fig. 5 shows another example of a page displayed by the browser. 
Figs. 6(a) and 6(b) show an example of HTML that causes the browser 
to display a portion of the page of Fig. 5. 

Figs. 7(a) through 7(c) show further examples of HTML that result in 
the portions of page of Fig. 5. 

Figs. 8(a) and 8(b) show several examples of ORM (Object Resource 
Management) requests made by the server to the object manager and the 
resulting responses from the object manager. 

Fig. 9 shows another page displayed by the browser. 

Fig. 10 shows layers of functions available to the object manager. 

DETAILED DESCRIPTION OF PREFERRED EMBODIMENTS 

Reference will now be made in detail to a preferred embodiment of the 
invention, an example of which is illustrated in the accompanying drawings. 
Wherever possible, the same reference numbers will be used throughout the 
drawings to refer to the same or like parts. 
I. System Overview 

Fig. 1 is a block diagram of a computer system 100 in accordance with 
a preferred embodiment of the present.. invention. Computer system 100 
includes a first computer 1 10 and a second computer 120. First computer 110 
and second computer 120 are connected together via line 106, which can be, 
for example, a LAN, a WAN, or an internet connection. Line 106 can also 
represent a wireless connection, such as a cellular network connection. 

First computer 110 includes a CPU 102; a memory 104; input/output 
lines 105; an input device 160, such as a keyboard or mouse; and a display 
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device 150, such as a display terminal. First computer 110 also includes an 
input device 161 that reads computer instructions stored on computer readable 
medium 1 62. These instructions are the instructions of e.g.. browser software 
130. Memory 104 of first computer 110 includes browser software 130, 
Hypertext Markup Language (HTML) 135, and objects 132. A person of 
ordinary skill in the art will understand that memory 104 also contains 
additional information, such as application programs, operating systems, data, 
etc., which are not shown in the figure for the sake of clarity. 

Second computer 120 includes a CPU 102' and a memory 104'. 
Memory 104' of second computer 120 includes server software 140, an object 
manager (ORM) 142, and objects 144. HTML 135 in the memory of first 
computer 110 was downloaded over line 106 from server 140 of second 
computer 120. A person of ordinary skill in the art will understand that 
memory 104' also contains additional information, such as application 
programs, operating systems, data, etc., which are not shown in the figure for 
the sake of clarity. Server 140, object manager 142, and objects' 1 44 can also 
be located in memory 1 04 of first computer 110. 

It will be understood by a person of ordinary skill in the art that 
computer system 100 can also include numerous elements not shown in the 
Figure for the sake of clarity, such as disk drives, keyboards, display devices, 
network connections, additional memory, additional CPUs, LANs, input/output 
lines, etc. 

The following paragraphs provide a general discussion of the World 
Wide Web ("the Web"). The Web is built around a network of "server- 
computers, such as second computer 120, vyhich. exchange requests and data 
with each other using the hypertext transfer protocol ("http"). A human 
designer designs the layout of a Web page, which is then specified using HTML 
("Hypertext Markup Language"). Several versions of HTML are currently in 
existence. Examples include HTML versions 2.0 and 3.0, as specified by the 
WWW Consortium of MIT. The HTML used in the described embodiment of 
the invention includes frames, forms, and tables, as are known to persons of 
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ordinary skill in the art. 

A user views a Web page using one of a number of commercially 
available "browser" programs. The browser submits an appropriate http 
request to establish a communications link with a Web server of the network. 
A typical http request references a Web page by its unique Uniform Resource 
Locator ("URL"). A URL identifies the Web server hosting that Web page, so 
that an http request for access to the Web page can be routed to the 
appropriate Web server for handling. Web pages can also be linked graphically 
to each other. 

Fig. 2 is an additional block diagram of a computer system in 
accordance with a preferred embodiment of the present invention. Browser 
130 communicates with server 140. Server 140 includes an http adapter 202 
and a management gateway 204. Http Adapter 202 handles communication 
via the known http protocol. Management gateway 204 communicates with 
object manager 142. Server 140 communicates with one or more objects 132, 
144 using a request/response (RR) protocol, such as the ORM (Object Resource 
Management) protocol, which is discussed below. Note that objects 132 and 
144 can be located oh the same or different physical computers or machines. 
Server 140 also communicates with external interface 206, which 
communicates using the known SNMP and CMIP protocols. Server 140 also 
communicates with external gateway 208, which communicates using the 
known SNMP and CMIP protocols. The system can contain more than one 
servers 1 40 and more objects than are shown in Fig. 4. 

Fig. 3 is a diagram of data sent between a browser, server, and object 
manager in accordance with the embodiment of Fig. 1, In the example of Fig. 
3, the user has already begun execution of browser software 130. In step 
302, the user enters the URL of server 140 by way of browser 130. The 
browser sends a request to the server and, in step 304, the server responds 
with the HTML to generate a home page. The home page allows the user to 
enter a URL (or to chose a URL from those known provided within the HTML of 
the home page). The user can then chose to set/browse objects in the system, 



"^098,02831 PCT/US97/11885 



10 



15 



20 



25 



30 



35 



as described below. The user can also request information and statistics about 
once or more objects in the system. 

In step 306, the user enters a URL of an object by way of browser 
1 30. Server 1 40 converts the URL to a request to an object manager. For 
example, in the described embodiment, server 140 converts the URL to an 
ORM request, as described below. The ORM request is sent to the object 
manager, which returns object data in steps 308 and 310. Server 140 
converts the object data into HTML, which is sent to browser 130 in step 312. 
The HTML may be based on a predetermined page template known to the 
server. Alternately, the format of a page may be determined "on the fly" based 
on the information obtained from the object manager. Server 1 40 converts all 
pathnames, such as object-links in the object data (see Fig. 4) to URLs in HTML 
and vice versa. Thus, if a user clicks on an area in a page displayed by the 
browser that corresponds to an object-link, browser 130 has the URL 
corresponding to that object-link. This new URL is sent to the server, which 
obtains the page information and sends HTML to display information for the 
object connected to the object-link. 

Steps 314 through 320 represent a "set" mode, in which the user 
enters new values for an object by way of browser 130. In step 314, the user 
indicates that he wishes to' enter "set" mode. This indication is usually 
accomplished by clicking on a button in the current page (thus, the HTML 
generated by server 140 should include HTML for- this button). In step 316, 
server 140 sends a "form" for set mode. In step 318, the user enters new 
values into the form and clicks on "submit" (or "apply", (see Fig. 5), as is 
known to persons of ordinary skill in the art. Server 140 converts the 
submitted form to, for example, an ORM request, as described below. The 
ORM request is sent to the object manager, which returns object data in steps 
317 and 319. Server 140 converts the object data of step 319 into HTML, 
which is sent to browser 130 in step 320. 

Steps 322 through 332 represent a "browse" mode, in which the user 
views values associated with an object by way of browser 1 30. In step 322, 
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the user indicates that he wishes to enter "browse" mode. This indication is 
usually accomplished by clicking on a button in the current page (thus, the 
HTML generated by server 140 should include HTML for this button). In step 
324, server 140 sends a "form" for browse mode. In step 326, the user 
enters new values into the form and clicks on "submit" (or "apply", see Fig. 5), 
as is known to persons of ordinary skill in the art. Server 140 converts the 
submitted form to, for example, an ORM request, as described below. The 
ORM request is sent to the object manager, which returns data corresponding 
to the object in steps 328 and 330. Server 140 converts the response of step 
330 into HTML, which is sent to browser 130 in step 332. 

II. Hypermedia Object Management 

A. Object Organization 

Fig. 4 is a diagram of a format in which objects are organized in a 
preferred embodiment. This organization is transparent to server 140 and 
browser 1 30. It will be understood that the present invention can be used with 
a number of object organizations and with a number of object management 
protocols. The embodiment described herein uses the ORM protocol, as 
described below. 

The model of Fig, 4 assumes the following: ♦ 
1) Management operations can be mapped to two basic operations: 
a) Get an attribute (or a set of attributes) of an object and b) set an attribute 
(or set of attributes) of an object. 

2) All entities to be managed can be organized as a directed tree with 
nodes and leaves where the nodes are either (callable) objects or components 
(sub-parts of objects) with attributes as the leaves (with combined name/pair 
values), and 

3) All knowledge about management operations and attributes is built 
into and controlled by the managed object. 

Fig. 4 shows the following types of entities; 
1) Objects 

Objects encapsulate and control management aspects and respective 
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management operations. In the descnbed embodiment, an object is identified 
by a "pathname." which is the destination for object calls. Each manageable 
object has its own virtual tree of components, attributes, and object-links. 

2) Components 

Components are the primary structuring mechanism within an object. 
Component sub-trees may be of arbitrary depth and component nodes may 
contain any number of object-links, other sub-components, or attributes. 

3) Attributes 

Attributes describe specific aspects of a component within an object 
(for example, "status = running" describes the state of a resource). Attribute 
nodes have additional properties beyond name and value, such s access mode 
and data type. Attribute nodes are leaves and do not have children. 

4) Object-links 

Object-links contain an object reference to a related object. As every 
object is responsible for its own virtual tree of resources, one object can 
provide a reference (hyperlink) to another object. Thus, in the described 
embodiment, a first object can have links to a second object, so that objects 
can be "yvalked" by way of browser 130. 

5] Relations ' 
Objects and components are the primary means for structuring and 
navigation in the described embodiment. Attributes have values that 
characterize the state of the resource. All operations (browsing and attribute 
retrieval/setting) are performed with respect to a single level of the tree (e.g., 
relative to a specific parent). 

Server 1 40 preferably Issues the following requests to object manager 
142: 

1 ) Get a list of linked objects, 

2) Get a list of components and/or sub-components, 

3) Get a list of attributes, 

4) Set a list of attributes (Along with name/value pairs for each 
attribute), and 
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5) Get an extended list of attributes, which returns meta-information 
about the attribute, such as data type, allowed access mode (ro, rw) or valid 
ranges of new attribute values. Within the ORM model, all management 
operations are mapped to these five operations. Thus, every managed object 
preferably supports these five operations. 

It should be understood that the attributes and object types shown in 
the examples herein are included only for the purposes of example. The 
present invention can be practiced using any appropriate object organization 
and type. 

B. Server Interface 

In the described embodiment, all messages passing in and out of server 
140 are ASCII messages. 

A example URL for object 402 of Fig. 4 would look like: 
Http ://ham/get/object Root/Component 1/Component2/ 

A example URL for attribute 404 of Fig. 4 would look like: 
Http://ham/get/objectRoot/Component1 /Component2/Attrl / 

In both of these URLs, "ham" stands for "HyperMedia Adapter to 
Management" and represents the address of server 140; "get" (this could also 
be "set"} represents an operation to be performed on an object or attribute; and 
the remainder of the URL represents the tree of the object or attribute known 
to the object manager. Other URLs may also include additional information 
use, for example, by the object manager. 

Fig. 5 shows a page displayed by browser 130 in "set" mode. Fig. 5 
shows the values of attributes for a "Configuration" object component. These 
attributes include: 

1 ) Status 520, 

2) Maximum Concurrency 523, 

3) Trace Level 524, 

4) OSL Traces Enabled 526, 

5) Script directory/Vol. 528, 

6) Script File 530, 
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7) Cache Tel Scripts 532, 

8) Tel Trace Enabled 534, and 

9) Maximum Size of Synthesized Page 536. 

Rg. 5 also shows an entry 522 for changing the status attribute. It 
should be understood that the attributes of Fig. 5 are presented for the sake of 
example only and are not to be taken in a limiting sense. Fig. 5 also shows a 
reset button 540 and an apply button 550. When the user clicks reset button, 
original attribute values are returned. When apply button 550 is clicked, 
browser 1 30 posts a form, as is known to persons of ordinary skill in the art. 

Figs. 6(a) and 6{b) show an example of HTML generated by server 1 40. 
When browser 130 interprets the HTML of Fig. 6, it generates the portion 
containing attribute values 520-536 and buttons 540, 550 of Fig. 5. Figs. 7(a) 
through 7(c> show an example of HTML generated by server 140. When 
browser 130 interprets the HTML 702, 704, and 706 of Figs. 7(a) through 
7{c), it generates portions 502, 506, and 504, respectively, of Fig. 5. 

Fig. 9 shows another page displayed by browser 130' in accordance 
with HTML generated by server 140. The page of Fig. 9 is used to browse 
objects, -but cannot change the attributes of objects. 

The previous paragraphs discuss the browser GUI presented to the user 
and how server 140 translates between HTML and a protocol understood by 
25 the object manager. The following paragraphs describe the protocol used to 

communicate with object manager 1 42 about objects and to change objects in 
accordance with the HTML received by the server. 

Figs. 8(a) and 8(b) show several examples of CRM requests made by 
the server 1 40 to object manager 1 42 and the resulting responses from object 
30 manager 142. Pages of the description shows formats of such requests 

and responses. Request 802 is an example of an OrmGet request sent from 
server 140 to object manager 142. The format of an OrmGet request is: 
OrmGet: pathname 
entity types 

where pathname is a name of an object or an attribute. Possible entity types 
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are: "Object" (all known objects at this level), "Component" (a list of all 
components below the level of the path specified in the OrmGet), "Attribute" (a 
list of attributes for the current node; for every attribute, its name and 
"stringified value is returned; if the pathname already navigates to an attribute, 
the object manager returns the empty string), "Info" (returns "meta-attributes" 
such as mode, range and unit), and <none> (i.e., an empty string). 

In request 802 of Fig. 8, the server "knows" about an object 
"HyperMedia Adapter NSK", possibly from receiving a URL from browser 130. 
Line 820 represents a version of the server (e.g., version 1.0). Line 822 is an 
"OrmGet" request for object "HyperMedia Adapter NSK". Server 140 requests 
information from object manager 142 about entity types (Info), Component, 
and Object (lines 824). 

Response 804 is generated by object manager 142 and sent to server 
140. The object has four components, no info, and no objects at the same 
level. As seen in step 312 of Fig. 3, server 140 generates HTML 604 of Fig. 
7(c) in accordance with response 804 and sends the gerrerated HTML to 
browser 130. 

' Assuming that the user wants to browse information about the 
Configuration component of object "HyperMedia Adapter NSK", browser'130 
sends a request to server 140 to this effect. Server 140 then sends request 
806 to the object manager, which responds with response 808. Request 806 
is similar to request 802, but the pathname in line 830 is "HyperMedia 
Adapter NSK/Configuration". 

Response 808 includes attributes for the "Info" entity. Thus, the 
response includes an attribute value, mode, field, and range for each of ten 
attributes of the component "Configuration". As seen in step 332 of Fig. 3, 
server 140 generates the HTML of Figs, 6(a) and 6(b) in accordance with 
response 808 and sends the generated HTML to browser 130 (see Fig. 5). 

Assuming that the user wants to change one or more attributes of the 
Configuration component of object "HyperMedia Adapter NSK", browser 130 
sends a request to server 140 to this effect (assuming that the browser is in 
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"set" mode). Server 140 then sends request 810 to the object manager, 
which responds by sending a status value (not shown). 
A format of the OrmSet request is: 
OrmSet: pathname . 
Attribute: name 
Value: val 

where "name" and "val" respectively, represent an attribute name and an 
attribute value. This command is shown in line 840. The command can 
Include more than one Attribute/Value pairs. 

In the example, request 810 specifies new values for eight attributes of 
component "Configuration." Assuming that no error occurs when the object 
manager changes the attribute values, server 140 generates HTML reflecting 
the new attribute values in accordance with the response and sends the 
generated HTML to browser 130 (not shown). 

A preferred embodiment of the present invention has a server that 
interfaces with "self describing" (or "introspective") objects. The server sends 
requests to and receives responses from an ORM (Object Resource Manager). 
The system may include more than one ORM and more than one server. Each 
server may "know" about zero or moVe ORMs. Thus, the system is not 
centralized and does not necessarily depend on a central point to interface with 
the objects. 

C. The Object Manager 

1 . Self Describing Objects 

Fig. 4 shows an example of object organization in a preferred 
embodiment of the present invention. Pages of the description, shows 
examples of an ORM Server Support Library API (Application Program 
Interface) supported by the object manager to access objects in a preferred 
embodiment of the present invention. The routines in the API of pages are 
used by object manager (e.g., ORM 142 of Fig. 1) to receive requests from 
server 1 40 and to prepare responses to the requests. It will be understood be 
persons of ordinary skill in the art that any object manager can be used in 
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conjunction with the present invention, as long as the object manager is 
capable of communicating with server 140 and of fulfilling GetOrm and SetOrm 
requests from server 140. 

Fig. 10 shows layers of functions available to the object manager. A 
Protocol layer 1002 handles the ORM protocol, e.g., decodes the request from 
server 140, initiates the corresponding functions, and assembles an ORM 
response. Protocol layer 1002 is the lowest layer and drives all calls to the 
upper layers by calling "registered" functions. A Node layer 1004 handles 
navigation between nodes, ie.e, parsing the pathname to locate the virtual 
node, which represents some management entity. 

A Handle layer 1006 maps "virtual nodes" to real objects/data. Such a 
mapping results in a "handle." Handles are explicitly requested and released. 
An Aspects layer 1 008 handles instances that are made up from more than one 
ORM tree. For example, the "statistics" Component is not a single Component 
n the tree, but is generated by the object manager. As another example, some 
attributes depend on others and cannot be modified independently, but have to 
be treated as a single, atomic operation. These groups of attributes within an 
instance are called "aspects" and the corresponding Aspect layer is provided to 
extract and modify groups of attributes within an instance. 

An Attribute layer 1010 retrieves or updates a single attribute (of an 
aspect) and provides the meta information corresponding to this attribute. A 
Conversion layer handles the actual conversion of attributes between the 
external (ORM) and the internal (native) presentation. This layer also converts 
states and bitmaps to "friendly strings." 

2. Web Agents 

In another preferred embodiment of the present invention, the objects 
are not self-describing. In such an embodiment, one or more servers 140 in 
the system performs a "worm" function, i.e., one or more servers 140 follow 
object-links between objects and save all the information available concerning 
those objects. When a request is received from browser 130, server 140 
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sends its collected data to browser 1 30 (assuming that the collected data is 
not older than a threshold age value). 

In summary, the present invention allows a user to manage objects by 
way of hypermedia, such as the world wide web. In a preferred embodiment, 
the objects are self-describing and respond to questions about themselves from 
one or more object managers. A server communicates with the object 
manager{s) and generates HTML from responses received from the object 
manager. Conventional browser software allows a user to indicate which 
objects he wishes to browse or change. Using a conventional hypermedia 
request/response protocol, the browser and server communicate to obtain 
information about objects and their attributes. The server also translates 
HTML/URLs received from the browser to requests to the object manager. 
Such a system allows a non-centralized object management system. 

Other embodiments will be apparent to those skilled in the art from 
consideration of the specification and practice of the invention disclosed herein. 
It is intended that the specification and examples be considered as exemplary 
only, with a true scope of the invention being indicated by the following claims 
and equivalents. 
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5. Browse (readorxJy) and Change (read write) modes arc differentiated by different 
URL's. For tl\e Change mod an HTML input form is created with user interface ele- 
ments dependant on the meta information provided with attributes. Dependant 
from this meta information, simple text input-or numeric input fields, popup boxes, 
or radio buttons are generated. 

6. A submit of this HTML form results in an HTTP POST request, which appears at the 
managements adapter with a special URL and the list of name/value pairs from the 
input form- These values can be checked against the information now retrieved from 
the object (see above) and a ORM SetAttribute request is send to the respective 
object. This object iiuhates the intended state changes or returns an error to the 
adapter, which then creates a new page, which reflects the outcome of the operation. 

7. Access control can be cither applied by the generic HTTP adapter, filtering POST 
methods for example or by the called object itself using principal identifiers in the 
ORM request. 

53 Events and Alerts 

Compared to SNMP or CMIP OEM has no event or trap mechanism- With this respect it 
is much closer to the NSK management protocol called SPI. Instead event and alert sup- 
port is provided by another mechanism (and object) within MSF, called Alert Facility, 
which is built on top of the Common Execution Environment (CEE). 
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6.0 ORM Protocol 

6.1 General Characteristics 

The ORM protocol is a simple request response protocol constructed out of lines of ASCII 
text and terminated by newUne, to browse through the managed object and change its 
state. In this way, it is directly comparable to the HTTP protocol. 

■ 

It is bytestream oriented, as it contains no length fields or has any fixed structure, but the 
individual items are separated by special characters, i^. colons and newiines. 

» 

The logical end of a protocol uiut is determined by an empty line Le. a line with a newiine 
character as the first character. 

Remark: The decision for a pure ASCII protocol may be surprising, as M5F has a well 
defined presentation layer/ protocol by IDL/PCU/GLU, but ORM is designed to support 
self contained object management e.g. all manageable aspects of an object should be 
described by the managed object (or its maiuger) itself and just known by it. This 
implies, that a lot of human readable information has to be shipped with this protocol 
and using a pure ASCII protocol seemed quite rutural. In addition the browsing nature of 
the protocol would have resulted in a quite unhandy EDL structure of unbounded 
sequences of any's or unbounded strings, probably with another layer of \mbounded 
types above. Using ASCII strings simplifies the creation of protocol units. Last not least, 
ORM must also support the entities provided to build the MSF infrastructure itself, e.g. 
must also be available with and without these execution envirotunents. 

Internally the ORM protocol (ORM-P) is a tagged lirw protocol, as every line starts with a 
tag word followed by the tag value separated by a colon and termiixated by an end of line 
character (newiine). The protocol itself supports boxcarring (e.g. consolidated requests). 
Errors are reported irUine with the data i.e., where they occur^ by special error tags. 

Request and response uxiits are constructed the same way and the response is merely a 
''filled out" or "completed* request and as such, the information in it is self describing 
(i.e. need not necessarily correlated with the request). Hiis is not true for authentication 
ir\formation, which is not mirroied in the response. 

The ORM-P basically supports two kinds of operations: 

1. get entities (OcmGet) 

2. set attributes (OrmSet). 

The two keywords OrmGet and OrmSet at the beginning of every sub-request describe 
the intended operation (Le. are the operation tags). 

In addition to these two basic operations there is a preamble required for every (cor\soli- 
dated) ORM packet, identifying the originators protocol version (tag OrmVersion) and in 
the case of a request, there is an optional tag, to pass authentication information from the 
client to the server (OrmWho). 
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6.2 Pathnames: 

Pathnames provide the necessary navigation and identification information to locate a 
specific aspect -of an object (or its inteniaJ entities). The different parts of the pathname 
usually are also the names of the entities in the generated user interface and as such, 
should be "friendly", descriptive names, 

A pathname consists of a separated list of components, which in turn may contain 
any printable character including whitespace. 

For the current version, characters in the pathname components are restricted to the 
printable set of ASCQ characters but may be extended to cover all printable ISO-8859-1 
characters in the future (ORM-P is "S-bit dean", but this restriction is just to be mote flex- 
ible in the choice of user interface construction)* 

There are two special component names, which follow the POSDC convention for filesys- 
tem tree navigatioru and These are only allowed in conjimction with an OrmPath 
tag and refer to the current node and to the parent of the current node respectively where 
the "current node" must have been defined by a previous ORM sub*request in the same 
protocol unit (i.e. OrmGet or OrmSet), An attempt to traverse the parent of the root of the 
tree is treated as an erroneous pathrtame (compare with "cd" in a POSDC system). 

63 Error Reporting (OnnError): 

Errors are reported, where they are detected, i.e, the error tag (OrmError) usually appears 
directly behind the error causing tag in the response. This allows some kind of identifica- 
tion of the failed subrequest or protocol item even for large consolidated requests. 

An error tag in the response also indicates, where the request was aborted. Previous sub- 
requests in the same ORM packet may have been processed^. An error tog (OrmError) 
has a constant and a variable part where the constant part identifies the kind of error, the 
variable part is used for additional hints, what caused the error. As the error is reported 
with a context, this context provides valuable information for error explanations. 

The Format of an error protocol item: 

02nz&£rror:<deciJDal errorcode> <stringcode> : <variabie part* \n' 



6.4 Version Support: Orm Version: 

The first line in every protocol unit must identify the highest protocol version number, 
this protocol umit complies to. The actual version is 1.0! 



I . When the ORM requests axc issued via the IDL interface, the error il50 appears as an exception with the 
exception detail showing the actual ORM error code t 
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fig' 

OrmVersion: <ma. jor> . <ininor> 

A server/application may respond to this request with an error VersionMissmatch fol- 
lowed by its desired version id. 

6.4.1 Protocol Conformance ic Protocol Exrors: 

Unknown tags shouJd be ignored unless they appear at a posidon, where another tag is 
required (an attribute tag must be followed by a value tag for example). If the latter 
occurs, the unidentified or unexpected tag is pUced in the response messaee followed hv 
an error tag with "ProtocolFailurc" ^ 

6-5 Principal Identification Information: OrmWho 

For the purpose of propagating the identification of a principal causing the request or to 
be used with the request ORM-P supports a protocol item.to ship any kind of (encoded^ 
principal identifier with a request in the following way: 

OnnWho: <principal idencifier> 

Up to now neither the <id^eme> nor the encoding or interpretation of the "encoded- 
principal-Identifier'' arc specified in any detail by ORM-P but are up to the appUcation 
and require an agreement between the ORM-P client and server. This may be Tubiect of 
changed 

6,6 Browse Operation: OmiGet 

The operation tag "OrmGer has to be foUowed by a colon (-^ - the tag separator) and 
usuaUy IS foUowed by a "pathname". As every ORM protocolitem, thIopWation tag fol- 
owed by the optional pathname has to be tenninated by a newline character. This fSs t 
line IS foUowed by a list of entity type sped^fers requested. 

6.6.1 Entity Types 

The OrmC^ request is foUowed by a Ust of type specifyers to describe the kinds o f entities 
requested for browsing. Mowed types (and entity spedfyers) are: 

• Object 

requests a list of aU known object links at this level. A Wendly name and the link- 
address (NOR) is returned per object 

• Component 

A list of aU components below the level of the path specified in the GET Une is 
requested. A list of names is returned. 

• Attribute 
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A list of attributes f r the current node is requested. For every attribute its name 
(Name:<name>) and its stringified value (Vai«tf;cvalu ) is returned. If the path in the 
OrmGet line already navigates to a single atti&ute, the returned name is the empty 
string. 

• [n/o (implies Attributes) 

This type addresses the same type of entities as ''Attributes'', but here meta informa- 
tion in addition to the name /value pair is requested, as there is Field for identifying 
the type of input expected. Mode to describe the access mode (read, read-write or 
v^aite) and the so called hints {Range and Unit), which can be used by the user-interface 
to generate a more sophisticated presentation of the attribute. These injb fields are 
described below in detail in the response section. 

• <Empty> 

An empty type spedfyer indicates that the validity of the pathname should be 
checked, but no information is requested. 

As all ORM protocol items, every single type spedfyer is termiruted by a newline. 
Examples: 

1 ) OnoGec : / telnet /windows \n 
Component \n 
\n 

2 1 OrroGet: /telnet/windowsyiptyl/statuaSn 
Attribute\n 

OrmPAth: . , / . . /pty2/3tatus\n 

Ac tribute \n 

\n 

3 ) OnoGe t : / telnet \ n 
Object \n 
CoxDponentVn 
Xn£o\n 
\n 

Note: Leading biaxUcs in front of the tag or the tag value are igrwred as well as lines, 
whose first character is a "IT. 

The OrmGet request may be called without a pathname specification (e.g. "OrmGet: Vn") 
in whidi case the root object itseU is referenced and the otdy valid ty^ 
"Object*/which wxU return the "friendly' naxne of this objert 

(Note: this link address may be another one. as the request was sent to^ i.e. this allows 
redirecting the management requests to another object reference). 

6.6J1 OrmGet Response 

The respoi\se to a OrmCet request nieirely mirrors the request but here the type spedfyers 
are used as tags (to type the following entity) followed by tiie name of the entity (sepa- 
rated by ":") followed by a newline character: The name item is followed by a type 
dependent list of additional tagged items, describing further properties of this entity. 

Although the partial responses below are listed per ptity type, they appear in the same 
response unit in the same sequence as in the correspionding request unit, Le. if the latter 
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reqtxested entity types by the sequence ''Object\nC mponentXAttributeXn", then the 
response will first list all available objects at this level followed by ail available compo- 
nents followed by ail available attribute/ value pairs. If a requested type is not available 
at the specified level an empty tag of that type (with a colon) is returned. 

The response unit for an OrmC^t request starts with the common response header (i.e. 
OrmVersion:<uer5wn>) followed by the "OrmGet <pathname>'' line followed by any 
number of the follo%ving constructs. 

S.63 Object Entities: 

Syntax: 

<object-icem> ::= *Object' (*:' <striiig> *\n' 

<object-linloj *\n' 
<object-link> •Link' <st:ring> 

Example: 

Object : Network Service Layer\n 
Link: <obj-ref erence>\n 
Object: Media Access Layer \n 
Link : <ob j - re f erence> \ n 

\n (if this is the end o£ the response!) 

6.6.4 Component Entitiefl: (have no additional properties) 

Syntax: 

<coinponent-iteia> ;:= 'Component* (*:' <3tring>l~ "Nn*- 

Example: 

Component :Confi9uration\n 
'Component : Statistics \n 

\n (if this is the end of the response I) 

6.6.5 Attribute Entities (simple request) 

Syntax: 

<attribute-it«m> ::« ■Attribute* (•:' <atrinig> "Nn* 

<attribute-valu«> J • \n • 
<attribute*value> *Valu** <atrittg> 

Exaaiple: 

Attribute : Packets sentVn 
Value: I234\n 

Attribute : Packets r^ceived\n 
Value:4321\n 
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6.6.6 Attribute Entities (Info request): 



Syntax : 



<actribute-item> ::= 



•Attribute' (•:' <striiig> 
<attribute-in£o> | 'Vn'! 
<attributc-in£o> <attribute-vaiue> •\n* (cnt) 

<atcribute-inode>'\n' (cnt) 
<atcribute-field> ^\n' (cnt) 
I <attribute-range> • \n' I 
(<atcribute-\init> *\n*] 
<attribute-tnode> ::=-Mode:' [ •RO' | "WO- | 'RW I C I 
<at tribute- £ieid>: := •Field:* <ORH-f ieldtypo 
<a t tribute- rango :: = "Range:* <ORM- range -de £inition> 
<attribute-unit> ::= -Unit:* <string> 



example : 

Attribute :Status\n 
Value : Running \n 
Mode : RO\n 
Field: StringSn 
Attribute: New Status \n 
Value : Running \n 
Mode : WO\n 
TyperEnumVn 

Range ; Stopped, Abort ed\n 



Here the sequence of the different info tags is not relevant but "Attribute" always starts a 
new property set for the next attribute. The "Range" and Unit^ tags are optional. 

For "Ol^-field type" and "OElM-rangeKiefinition" see below, 

Errors ic Exceptions specific to tiiis request 

• NoSuchNode: 

The path specified docs not point to a legal virtual node.This error is only reported 
inunediateiy after a ''Orm{Get/Set/Pathl:<patiKna2ne>* comnuind. 

• InvaiidOperation: 

The path spedfies a node, which can not sij^jport the requested entity type, an 
"Attribute* request for an "Object* node or vice versa for example. This error is 
reported after a type specifyet; listing the type spcdfyer (without a colon) followed by 
a newlixie followed by tiie enor tag. 

6.7 Modification Requests: OnnSet 

The set request starts with the set-tag "OrxnSet* followed by a pathname followed by a 
newiine. The pathname at minimum must contain the name of the root e.g. "/ <root- 
name>'' (i.e. an empty pathname is not allowed!). 
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This line is f Uowed by a sequence f line pairs containing the name of the attribute and 
its value, e.g. . 

Syntax: 

<attribute-icexa> ::= *Accribute' (*:• <scring> 'Nn* 

<actribute-value>| •\n* 
<attribute-value> "Value;' <string> 

Example: 

ACCribuce:New StatusXn 
Value : Su5pended\n 
Actribute: Reset Statistics Sn 
Value :Yes\n 

\n (if this is the end of the protocol unit) 

6.7.1 OnnSet Responses: 

If no error occurred, the response to the OrmSet request is a copy of the request itself. 
Otherwise an error-tag may appear somewhere in the response, and if the underlying 
request/ response protocol permits, the respor\sc is flagged with an error indicator. 

The effect of an erroneous OrmSet sub-request is application dependant, but it is recom- 
mended^ that a OrmSet sub-request either succeeds completely or has no effects at all 
(atomicity). 

Any OrmSet requests preceding a failed one are not affected, any subsequent requests are 
ignored* 

6.7.2 EzTDr-Rehims: 

• NoSuchNode: 

The path specified does not point to a legal virtual node This error is only reported 
immbediately after a ''SET:<pathxiame>'' command 

• NoSuchAttribute: 

The string following an ^Attribute:" tag does not identify a legal attribute. The error- 
tag follows the "Attribute:'* tag (indudiing the string). 

• ValueOutOfRange 

The value specified is not within the range of legal new values for this attribute. The 
error tag follows the value-tag line. 

• Valuelnconsistent 

The set of attribute values in the request were no consistent or contradictory 

• [nvalidOperation: 

The desigt\ated Attribute is not writeable. 

• NoPermission: 

The access rights of the requester do not alloyv to set the designated attribute.(This 
error and the previous one may have some overlap) 
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6.8 Request Type Independent Errors: 

• ProtocolError 

If pairs of tagged lines are expected and the sequence of pairs is not completed or an 
unknown or context illegal tag is detected, this error is generated, following the erro- 
neous tagged line. 

• IntemalError 

An internal error in the application/server was the cause, that this request could not 
be completed, (allocation failure, mangled structures). This indicates a severe error at 
the server side. 

• BufferTooSmall: 

The response buHer specified is too small to return the hill response. 

• NoSpace: 

Some internal buffer could not be allocated or was to small for the requested opera- 
tion. 

6.9 ORM Attribute Info Descriptions: 

Within the ORM protocol there are two ways to retrieve an attribute: the short form 
returns jixst the name of the attribute and its value and the long form* returning addi- 
tionai meta information for every attribute, which can be used to create reasonable user 
interface elements by the ORM dient 

The following fields appear n the extended desmptioru 

- Field: identifies the kind of field, this attribute should be presented in 

- Mode: ideadfies applicable operations (readonly, read/write, writeooly) 

* Range: Provides hints for input cheddng and for user interface geceration 
. Unit: a free form field often describing the metric of the value or scale. 

6.9.1 ORM Field Types: 

Although in principal, the ORM field type item {Field) allows any principal character 
string, the ORM support library and the user interface generator (HTML syndiesizer) will 
ordy support a limited set of predefined field types, to ease the presentation of attributes. 
If a field type is iu>t recognized, the default "String'* is assumed. 

6.9X1 Field: Integer 

The ORM protocol does not distinguish between unsigned and signed integers, e.g. every 
asdi string representing an integer niay.be prefixed by a or a There is also no size 
information in the field type. Any range restrictions have to be specified in die Range sec- 
tion. 

Syntax: 
Ficld:lntcger 
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6.9.1^ Field: Real 



The field type Rrcd idendfes decimal floating point values. The allowed input formats are 
those of the POSIX 10032 scanf function for float and double values. 

Syntax: 
Fteld:Real 

Ficld:HcxOctet 

This field type is used to display and enter binary data as pairs of hexadeamal character 
Syntax: 

Field:HcxOcict (a sequence of hexadecimal digits) 
6.9.1.4 Compound-Field Types: 

The last set of field types allow much finer control of the input, an end user may provide 
to the ORM-P client side (or the client of the client...). These types are named Enum and 
Set, where Enum specifies a "one out of m" field and Set specifies a "n out ofm" field. 

Both types arc only valid with an appropriate Range field in the hints section^ where the 
possible alternatives must appear in a comma separated list 

These two types often transformed into ^Pop-Up" menus (Enum) or option lists {Set) or 
similar by the user interface generator. 

Syntax: 

Field: Eniun (single selection from *Raage:') 

Field: Sec (multiple choices from *Range:') * 

6.9^ ORM Attribute Modes: 

To generate reasonable user interfaces (as far as possible without object/component spe- 
cific knowledge), the generator must know, whether an attribute is "tead-only^, "read- 
write'' or "write-only^. The latter is used to signal to the user interface^ that this attribute 
should be only shown on "change-attribube'' frames, if those are distinguished foam pure 
browsing fracnes. An extension to these basic modes is provided for writable attributes to 
indicate, tiiat an attribute value is mandatory, by appendixtg the letter "M" 

■ 

The different modes are simply encoded as twoletter strings followed by an optional 



-P", eg. 



Syntax 



- RO 

- WO(MI 

- RW(M] 



Read-only 

Write-Only Cnon- null value mandatory] 
Read-Write (non-null value mandatory] 
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6.9-3 Range Identifiers: 

The range identifier, tagged with "Range:* is used as a kind of hint (and therefore it is 
optional except for the compound fields) to the user interface generator, what kind of 
input/ output field it should generate. In addition the information can be used to check 
any optional input and give the end-user appropriate responses or hints, if these input 
checks fail. 

The range hints are type specific and as such different conventions are defined to specify 
valid ranges for an input field. The type independent convention is to separate alterna- 
tives by a comma and sequences by three subsequent dots 

6.9.3.1 Range Specifications for integer Fields: 

Valid range specifications for the integer types are: 

Range: 1. 4.8. 16 valid: 1 of the values listed 

Range: 20. . .60 valid: all numbers between 20 and 60 including 

Range :0... valid: every integer including 0 (up to typemax) 

Range: -20. . .+20 valid: every integer between -20 and +20 incl. 
Range: valid: every pos/neg integer within type 

6.9.3^ Range Specifications fro Floating Point Fields: 

Valid range specifications for the real types are: 

Range: 0.1, 0.5. 0.8 valid: one of the values listed 

Range : 0. le-3. . .0.1 valid: reals between 0.0001 and 0.1 



6.933 Range Spedficationfl for String Fields 

If the first range value starts with a digit, the range indicates either the maximum or the 
rai\ge of vaUd string lengths. If the first duuacter is nonnumieric the range is inte^ 
similar to the comfKound Enum field below, Le. one of ttiese strings may be selected, but a 
diffexOTt user interface element may be used <a list box). If the first character of the range 
string is a comma this provided strings in the comma separated list are treated as 
examples, where the possible input is not restricted to the given alternatives. A ma|or use 
of this kind of string selection is in file selection boxes. 

Syntax: 

Range:1...20 valid: strings with miniawm length of 1 

and masc length OC 20 characters 
Range: 10 valid: a string with at max 20 characters. 

Range:. £ilel.c,£ile2.c "filel.c or file2.c arc valid options. but 

other input is also valid 
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6.9.3.4 Range Specification for Compound Fields: 

For the Enum and the Set type fields lists of alternatives are required in the range section. 
The comma separated list identifies the different options a user is allowed to select. 

Syntax: 

Range :<coirana separated list of aitematives> 
Example: . 

For Enum (choose one oC) 
Range : STOP , SUSPEND , ABORT 
For field type Set (choose n or none of) 
Range: Trace IP, Trace UDP, Trace TCP 



6.9.4 The Unit Specification: 

The "Unit" specification is a free form string and currendy not interpreted by the user 
interface generator If present, it will append this string behind the value field as one 
would do with a unit description like "1.4 inches''* Another important purpose of this 
field is for the use with customized object specific management pages (if used within an 
HTML environment). Here the unit could be used to identify an application specific type 
for example. 

6.10 Navigation Request: Path 

This request extends ttie previous operation {OrmCet or OrmSet) to a new subtree and fol- 
lows these tags in its syntax. It may appear everywhere, where a OrmGet or OrmSct tag 
may appears except that it must be preceded by one of these itcins in the same pro toco I 
unit It usually is orUy found in sequences of ORM statements resulting from a ''Oump" 
request! 

Syntax: 

OnaPatb: <pathnasEie> 

Semantics: Extends the previous OrmGet or a OrmSet request into aru>ther subtree within 
the same object 

6.11 Summary of ORM Error Codes: 

NToPermission: 1 

The current authenticatioa can hot be used to perform the requested operation 

MoSuchNode: 2 ^ 

The pathname specified ia a Orm(Gct/Set/Palhl request docs not point to a known 
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node. 

NoSuchAttribute: 3 

The attribute specified in a OrmSet request could not be found 

NoSuchObject 4 

The Object specified could not be found. 

[nvalidOperation: 5 

The operation requested is not valid for this type of enuty. (Example: attribute is not 
writable, request components of an attribute) 

ProtocolFailure: 6 

A sequence of tags was encountered, which could not be parsed and decoded. 

Versior\Missniatch: 7 

The object could not deal with the version of the request packet. 

CommtmicationError: 8 

This is a client side error to map lower level communicatioa errors too, if necessary. 

ValueOutOfRange: 9 

The value passed in with a set request for an attribute is not within the allowed range 
and could not be accepted. ' 

Vaiuelnconsistent 10 

The combinatioa of values passed with a set request is not acceptable. 

NoSpace: 12 

The request could not be completed because of internal space restrictions in the object. 
BufferTooSmall: 13 

The response to the request exceeds the size of the response buffer provided by the 
underlying protocol. 

IntemalHrron 14 
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ApplicationError 15 

These two errors are used to report back iraplcraentation problems like corrupt data 
structures, where the IntemaiError usually is generated by the ORM support library, 
the ApplicationError instead is issued by the higher "appiicadon" layers. 
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3,1 ORM Protocol Layer And Upcall Interfaces 

This section was generated from <stiiin> by CDOC on Sun Jan 29 17:00:50 1995. 
ORM Application Context 

Application Server Capsules may >erve different kind of requests and therefor may have 
multiple dom.uns of objects to be managed listening on multiple ports. Following the 
CRM model this may result in multiple parallel independani trees. 

The ORM parser supports this by maintaining an application context, which has to be 
passed to the protocol layer to handle a request (there is also an opaque call-contexi, 
which may be passed to the protocol layer, but this isn't interpreted by the ssl). 

The application context contains beside (an opaque pointer) to the (virtual) root of the 
virtual tree, mainly a list of tree/application specific function pointers. Before the first 
request can be passed on to the ORM protocol layer this context has to be established 
with the ORM SSL vu^ a call to ORM.Contextlnitialize. 

Accordingly there exists a function to inform ORM that this application context is not 
needed anymore (release). 

The following lists the function prototype definitions for actual functions to be provided, 
when establishing a context. 

Note: Some functions are defined to return pointers to character strings (ORM.String). If 
the ORM protocol handler is used it is guaranteed, that the same function will not be 
called, before the string is copied or otherwise not needed anymore. This allows the use 
of a single pnvnte siring buffers per function, if necessary. - . 

3.1.1 Authentication 

The following list of functions are included to enable an application to maintain its own 
authenticated context. The ORM protocol just allows to forward some authentication 
related information from the client to the server (WHO...). This is passed on to the appli- 
cation layer as is, if encountered by the parser. The aaual meaning of this data is applica- 
tion and user interface dependant. 

3.1.2 Function Type ORM_AuthenticateFunc 

Performs any necessary authentication or preparation of authentication structures. Usu- 
ally, the authentication information is used to setup some context in the call<ontext, 
which is passed to the node/handle layer upcalls. It is up to the application layer to 
free/clear such context after return from the protocol layer 
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E^ia ration: 

zroi^AppCii: r^r.texceef cjllccntexc, / • inV 
Cf04_S»: r a uc hat cinq /• in •/ 



Fields: 



catkontcxi An opaque pointer to any Vand of context, the cailer has estab- 

lished.This passed to the node and handle layer. 

authstring The string, the client passed in his request, if any Usually 

uid.passvv'd 

status ORM_E.VoError: if successful!, ORM_EPermission Denied, if 

authentication unknown. 

3.1.3 OR.VLAuthFuncDef 

This structure is used to pass the Authentication function to ORM.Contextlnitialize 
Declaration: 

tiypelef jr,r-ct hFj.ncTsg 1 

A J :: r.« r. i c 3 r. e r un c a u t h ; 



3.1.4 Virtual Node 6c Tree Function Types 

The following hsi of functions (function types) are used to access the virtual tree of com- 
ponents, attributes and linked objects. They usually don't deal with application specific 
data. 

« 

3.1.5 Function Type ORM_NodeLookUpFimc 

This is the central function for the traversal ofthe tree . 

Returns an opaque pointer to a virtual node, which may subsequently be called to 
retrieve properties or children of specific types. 

Declaration; 

typedet ■:?.M__ita-. j3 ( 'CRM^.NodelookUpFunc ) ( 

-P-M_App.:ai^Ccnce.xt.De-" caliccncext, / in -/ 

c:-O*_AppNocle0ei root, /• in */ 

C RM^S t r i ng ' pa c Khd-iie /•in-/ 

■--''>i„-^?r'^c"ieD^f 'node, /• out •/ 

:?:-!_:i,-:leT'/peD€f -nd" type /* out ■/ 

Fields: 
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callconlext is an opaque pointer to the application specific call context pro- 

vided with the Do.Request function. 

root Opaque Pointer to root of virtual tree. This may be NULL and is 

taken from the application context. 

pathtmttte is a / sepnrtited list of component names optionally preceded by 

the name of the object (e.g. if the first component matches the roots 
object name, strip it, else take the first component to be a child 
under the applications root). Support for un*x style directory navi- 
gation . and is highly recommended/ required. A pathname of 
applied to the root with request type Object should return the root 
name and the actual servers link address (NOR) 



node The opaque node pointer, if found 

ttdjypc The ORM_NodeType of the node found 

rctunt ORM_E\'o Error in case of success, or any other CRM error in case 

of failure. 



3.1.6 Function Type ORM.NodeChildNextFunc 

Used to subsequently scan the children of a single parent. Returns the next child of type 
type of parent parent, which logically follows the child returned by the previous call to 
NodeOtiidNextO, now passed in as kstcftUd, E.g. If lasichild is set to NULL the logically first 
child of this parent is rev]uested. If there are no children (of the requested type), then 
NULL must returnevl with ORM.St^tus set to ORM_NoError.. 

Declaration: 



opC A 1 1 « n r. e X c De r 



;4iJLccn::extr " in •/ 

rarenc, /* in ■/ 

iasr.chiid, /- in •/ 

•zype, /• in */ 

•,-hii(l. 



' out •/ 



Fields: 
calicontext 

parent 
lastchiid 



is an opaque pointer to the application specific call context pro- 
vided with the Do_Request function. 

Opaque pointer to the virtual parent node. 

Opaque pointer to the last child returned by a call to this function 
(in this request), or NULL to request the first child. 

The type oi entity, which is requested (ORM.ObjectType, 
ORM.ComponentType, ORM.AtlributeType or ORM^AnyType). 
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^if^ii Pointer where to store the reference lo the node found 

namff Pointer to n<ime of node found. 

returns status value. Possible status values, see beiow! 

3,1.7 Function Type ORM.NodeChildByNameFunc 

The little sister of ORM.NodeLookUp. Looks for a child with name childname directly 
under the given parent par^rnt. This function is primarily used within the processing of 
Set- Attribute requests. If there is no child with this name, return ISTULL and an error sta- 
tus (see beiow* 

Declaration: 

cypedcf CR.M_3ca:us v 'ORM^VcceChiidByNameFunc J { 

^P-M.^-PP^-a-l'^v-iexiiref callccn^exc, / • in •/ 

Cr.M_i\cp;::;cu&ef pa rem:, /• in ■/ 

: ?,v_5 c r i r. 7 ch i 1 dnam-s , / ' i.- • / 

' = y_A::t:N V3.=:re f --hi Id, /• out • ' 

> 

Fields. 

P^^^nt Opaque pointer to the virtual parent node. 

childname Name of the child (attribute), i.e. every printable char except ' /' 

^-'^'^^ Pointer where to store the reference to the node found 

child jype Pointer to type of node found. 

ORM.EXoError if child was found, else ORM.ENoSuchNode. 

3,1.3 Functioit Type ORM^NodeTypeGetFunc 

returns the type (enum ORM.NodeTypeDen of the given node. 

Declaration: 

crw_rtccw.'^?.eOei ,-*c%ie /• in ■/ 

Fields- 

<T pointer to a virtual node 
^^'^^<rns a valid type or ORM_NodeTypeUnknown. 



32 



wo 9g/02831 



PCT/US97/11885 



3.1.9 Function Type ORM.NodeNameGctFunc 
returns the name (ORM.StringJ oi the given node. 
Declaration: 

- y pe f C ^-M_ S c r ;i q ('CP M_M ■J.ebi amcG<5 1 F u nc ) ( 
CXX_^?cSc<ieC-6f r.i-e /* in ■/ 



Fields: 
noiii' 
returns 



a pointer to a virtual node 

a valid null terminated string of characters or NULL 



3.1.10 Function Type ORM.NodeNotFoundTrapFunc 

This function is kind of special by providing the application layer a chance, if the lookup 
of a node failed, to create that node. 

Normally, referencing a non-existent node in the pathname of an ORM request is treated^ 
as an error, except this \s an internal ORM restore request. Reloading an ORM tree into an 
application m.ny encounter subtrees, which where dynamically created by the application 
during a previous run (usually via a Ntru* subtree). 

This Kinction is totally application dependant and is not covered by the ORM-S5L other 
than via this hook. 

Declaration: 



In •/ 
ouc ■ / 



Fields: 
parent 
name 

« 

ncwtiodi: 
reiurtiT* 



Reference to parent node 

Name of node not found under this parent. 

Kind of ORM request (get/set/dump/restore) causing this lookup 
failure. 

Where to store the reference to the new node, if one was created. 

ORM.ENoError. if a node with the given name was created else 
ORM^ENoSuchNode. 
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3.1.11 Structure ORM_NodcFuncDef 

This siruciure bundles the virtual tree related functions for passing to Contextlnitialize 

Note: The ORM^N'odeNotFoundTrapFunc is not included in this function array, because 
it is application special anyway and must be passed explicitly, see Context InitialiseO 

Declaration: 

typ^dei: s cruet CRM^McdeFuncTag i 

CM NoceLcoy.UoFunc looicap; 
0 PM_N z ieChi 1 iNe x t F l;.- c ch i 1 dne x c ; 

.:SM_\';;ue i -d&yNdiT»-t-r :: c ch i lcli:yr,a.T.e ; 
ircij;.; -eTycer-eiFjn- cyp^gec; 
N ■ ^ -.-No-eG-i". r :::: : r.a.-negct ; 



3.1.12 Application Handles 

The following two hjnction types are used to link the virtual nodes in the tree to (parts of) 
actual application data instances, visible to the ORM support layer as opaque handles. 
When an application handle is requested from the application layer, real things happen to 
start and it is assumed, that the instances are valid and available, until explicitly released 
by the ORM layer. The handles together with the aspect (identifying the type of handle to 
the applicatiotw \vi!l be passed to the application specific functior\5, when actual values 
have to be .K\*ess«xl (either for sft'/ or iW). If these functions are not set in the ORM context, 
N'L'LL will bt? passed mto those calls for both, the handle and the handlecJass, 

3.1.13 Function Type ORM_HandleGelFunc 

Request (and lock) an actual handle (pointer to.an application level instance) and a han- 
dleclass based on the current virtual node and the current principal. 

Declaration: 

' t . . ' . : . ' vt:-' f ij r ; i v: int. e:-t c , / • in ■ .• 

■:?r \rr::r':^:,^i -cce, in • / 

* - ? ''L-*'^ = f : T y veCe • op, /'in*/ 

CHM Apchar.cle-eC "handle, /• out •/ 

CR>»_;-.c pA s c<?'.: ",2^ i 'a spect / ■ out • / 

Fields: 

CiUtconti'xi is an opaque pointer to the application specific call context pro- 

V ided with the Da.Request function. 

tiOiic Potnier to current Node. 

op Operation Code, e.g. ORM_Request 

handle Pointer, where to store the handle reference 
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asfKCi Pointer, where to store the aspect r ference 

returns ORM.ENoError if no error occured r any of the ORM error codes. 

3.1.14 Function Type ORM.HandleReleaseFunc 

Returns a given handle back to the application layer. This should be more understood as 
an unlock operation than a free! 

Declaration: 

cypedef Vwic! .( •0?>l_HandleP.ciea3eFunc ) ( 

CP-M^AppCcllCon^^extOef callcencexc , / ■ in ■/ 
CPX^AopKanaieDef hAndie, /' in «/ 

CRM AppAjp^ctDef aspect, /* in •/ 

- ^ -t: *■ T •/ c -=r e r .* p ' ^ * 

Fields. 

ui//uv.'/r.\f 15 an opoque pointer to the application specific call context pro- 

vided with the Do.Request function. 

handle a handle obtained via a call to HardleGet 

flsped Aspect as returned from HandleGet 

op Operation Code, e.g. ORM.Request 

3-1.15 Function Type ORM^ObjectLinkGctFunc 

Retrieve the Objtvi Link from a node of type Object given the node, the handle and the 
aspect. The statidard Handle Uyer functions just return the link stored in the corre- 
sponding tleld in the node struct. 

Declaration: 

typedef cr^>!_acitJ3 (•0PM_Har.dleCfciectlir.5cGe- Func ) ( 



Z A :: N 0 • 1-5 Ce r. ;; de , 

C,^«.^A.:p:-.an=l's::^t* r:4nclie, /• ir. *^ 

: * V r t .*'. :: - * * - • ' Cv<5C t , / * irk * • 

.• * . . ^ • :.-r.< • cue • / 



Fields: 

node Reference to node of Object Type 



handic Reference to application defined handle as returned from Han- 

dleGet 

asvct't Reference to application defined aspect as returned from Han- 



35 



WO 98/02831 



PCT/US97/11885 



link Location where to store the reference to the stringified link infor- 

mation 

returns ORM.ENoError if successful!, else ORM.InvalidOperation, if the 

node is not ot type Object 

3,1.16 Function Type ORM.AttribuleDescrGetFunc 

Retrieve the opaque reference unique to a node of type Attribute (usually the attribute 
descriptor), given the node, the handle and the aspect. The standard Handle Layer func- 
tions just return the pointer stored in the corresponding field in the node struct. 

Declaration: 

. ; y r-.-j c - ■: • ; ; ■ : a Ji *2 , / - in • / 

:?>!_ ippA-ip^-:. »spect, ' in •/ 

" :-.;-! A :;i:A : " i: :. c j : i.Tc- : ' 2ZZzi bde 5 c / '* ou c • / 



Fields: 

noiitf Reference to node of Object Type 

hamih* Reference to application defined handle as returned fron; Han- 

dleCel 

<3s/vc( Reference to application defined aspect as returned from Han- 

dleCet 

attribdesc Location where to store the reference to the attribute information 

returns ORM.ENoError if successfull else ORM.InvalidOperation, if the 

node is not of type Object 

3.1.17 Structure GRM^HandleFuncDcf 

This structure bundles the handle related functions for passing to Contextlnitialize 
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Declaration: 

■:R>l_.-;af;:;iePeled3t?F':r:c release 

CIC< ~ M 4 nd : eO b : e c ^ i r, <' j6 c r u .ic I i r. x ; 

CivM~Hir.ci:GA:t rifc;:tcDo5crO€cr-jhc atcrifc; 
) cr^w. Kar.aleruncOef ; 



3.1,18 Accessing Application Data: Aspects 

the following group of runciions (function types) has to be provided to access actual val- 
ues of the application either for retrieval or for updating. All functions in this group are 
mandatory, if the ORM protocol layer is used. 



3.1.19 Function Type ORM.AspectCallGelFunc 

This function retrieves an aspect from the application layer, e.g. a reference to a blob of 
native application data (a pointer to a (part of) an application data stnicture, or a 
response buffer ...). The ORM protocol layer calls this function once for every unique 
handle/aspect combination (and not per Attribute) within a single AttributeCet Request., 
[f the HandleCet Function returns a different pair or there are ho more attribute nodes to 
process, the current aspect is released! 

Declaration: 

z y :le : V ...i t -3 : - 3 ( ' 

C _ A. c p C- * r. ? - r e : 

Fields: 

hnndk Handle as retrieved from HandleCet 

aspect Aspect Reference, as retrieved from HandleCet 

current Where to store the reference to the current value (opaque) 



nannle. /• in " /- 

aspect, /• in •/ 

• rur renr, out •/ 



3.1.20 Function Type ORM.AspcclCalllnilFunc 

This function requests an asfHXt container from the application layer, e.g. a reference to a 
biob, where new attribute values can be selectivly written to to perform AttribuleSet 
requests. In addition hte application layer may return a reference to the current aspects 
values (cmp CallCet), which is passed unchanged to the CallSet routine. The ORM proto- 
col layer calls this function once for every-unique handle/aspect combination (and not 
per Attribute) within a single AttributeSet Request. If the HandleCet Function returns a 
different pair for a node or there are no more attribute nodes to process, the CallSet func- 
tion is called (Note: AspectRelease is only called for aspects retrieved via CallCet!) The 
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ORM SSL implementation of these functions copies the current values and returns a ref- 
erence to this copy in new and a reference to the current values in current. 



Declaration: 



A pcCet art rTe f 



.-.■i:-.aie, /• 1- 

•new. 



/' cut •/ 
/ ■ c-Jt • / 



Fields: 

handle Handle as retrieved from HandleGet 

aT^lKiit Aspt-vt Reference, as retrieved from I-iandleCet 

;r, :(' Where lo store the reference to the native blob to update with new 

attribute values (opaque) 

currcni Where to store the reference to the current aspect (opaque) 



3.1.21 Function Type ORM^AspectCallSctFunc 

This hjnction is called to actually apply the new attribute values for the current aspect by 
the appiicntion layer, it is up lo the aspect/application layer, to check the values in the 
request structure for validity and consistency and to determine which attributes got new 
values (by coniparis^^n with the LKwri/ values). In addition it is the responsibility of the 
aspea/appiication layer to deallocate any structures allocated by AspeaCalllnit. Only if 
the Set-Function is not called, the call to AspectRelease is performed. 

The ORM protocol layer calls Set-function once for every unique handle/aspect combina- 
tion (and not per Attribute) within a single AttributeS€t Request. If the HandleGet Func- 
tion returns a different pair for a node or there are no more attribute nodes to process, the 
CallSet hjnction is called (Note: AspectRelease is only called for aspects retrieved via 
CallCet!) The ORM SSL Implementation of these functions copies the current values and 
returns a reference to this copy in nfw and a reference to the current values in currtnX. 

Declaration: 



r.ir.Jie, /' in ■/ 

.if.fv^.-cc, / ■ in '/ 

r.ew. /' in 

current, /• in »/ 

•Li Jetail • out */ 
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current 
rsdetail 
returns 



Aspect Reference, as retrieved from HandleCet 

Where to store the reference to the native blob to update with new 
attribute values (opaque) 

Where to store the reference to the current aspect (opaque) 

Where to store a textual hint, why the call failed, if any. 

ORM_E\'oError if new values could be applied successfully, else 
ORM.ERange- 



3.1.22 Function Type ORM.AspectReleaseFunc 

Used to tell the application layer, tliai the reference retrieved via an AspectCet or Aspec- 
tinit call is no longer needed anymore by the ORM layer. This function is called, when 
GetHandle returns a new handle aspect call within a AttributeGet processing or a conver- 
sion in an AitributeSel processing failed. 

Declaration: 



.*. • - f - I - 1 - • - • " ' 
tea • ' 

) ; 



• L n * / 



Relds: 
handle 

currt'ftt 
reqtypt 



Handle as retrieved from HandleCet 

Aspect Reference, as retrieved from HandleCet 

Reference to data as returned from AspectCalllnit or Aspect- 
CallCei. 

ORM.RequestCet or ORM.RequestSet depending whether this 
dataptr resulted from an AspectCet or Aspectlnit call. 



3.1.23 ORM.AspectFuncDef 

This function groups the function pointers of the aspect layer 
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Deciaration: 

cyf^cdof r-.:ct CHX^A spoor FtincTag I 

TRM^AsiJer'-Ch 1 1 : r.i Fu::c rdllin; t ; 
0RM_A5p;2CtraiiSetrcr.t c^llset; 
CRM_ A.f p<2c t i o a sc f - : release; 

3.1.24 AUribufce Functions 

The following group of functions is called to actually perform the the single attribute 
Gel /Set and the corresponding conversions between the applications native and the 
ORM (ascii) presentation. 

3.1.25 Data Structure: ORM.AttributelnfoDef 

This structure is used to return the all the meta information and the actual value of an 
attribute, it is passed by reference to the application/attribute layer to be filled. Note: The 
string pointers do not point to valid buffers, when passed to the attribute layer! 

^■vdi-.e' -r.-i 3w:i-rr.i valj-i in I'z a^cii preaencaci^r 
".r 'rtii::.:.: Tht.' rdr.":e- string 

i;c-i:.r.d*: T;".-= ur.ic string 

Declaration: 

w y p<M-r : H r . .: - - - i :: j - e i n i; cTag i 

v-ilue; 

Jet; 
: :=:'!; 
range; 

• .:=Jv_.-.L:.f.:vUL^rn£30-=f; 

3.1.26 Function Type ORM.AltributeNativcToStringFimc 

This function converts the applications native value ol m attribute, specified by handle, 
aspect and the attribute descriptor to a C-string (ORM.String). 
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Declaration: 

cypedef cnM_5'.iva3 ( -CPW^Ac - ributeNat iveTc£c ringFuncX 
•l}^^r,\zpd&udleO-^r .handle, 

::\M_AccDat:aPtcCe: 
>:r-M i-r:.::g 



aspect, 

at c ciiociescr, 

dacaptr, 
' sc rvalue 



/• in '/ 
in •/ 
/- in «/ 
/• in •/ 
/• out •/ 



) ; 



Relds: 
handle 
aspect 

attnbdt/^cr 
Jataptr 
$t rvalue 
returns 



Handle as obtained from the last call to HandleGet or NULL 

Aspect as returned from the last call to HandleGet or NULL 

Attribute Descriptor as returned form AttribDescrCet call. 

Opaque Pointer as returned from AspectCetCail. 

Where to store the reference to the converted value. 

ORM ENoError (Null) if conversion was successful!, else a valid 
ORM Error return code. 



3,1,27 Function Type ORM.AttribuleNativeToInfo 

This function performs the same as the previous function ORM_AtiributeNativeToSlring. 
excevi that it also provides the additional meta information to this attnbute, as far as availa- 



except 
ble- 

Declaration: 



yptidef CP.M_5La-u.3 ,-*c=;.M .^'--ribct^tiativeTcInfcFcncl t 

handle , in " * 



CHM_AppHandie2e t 

■ •• ■ .,- .r» »',»• 



4 4 • I 



) ; 



aspect, / 
acr ribcescr , / 

into 



/ 

in •/ 
in •/ 
i.-\ •/ 
in, inc 



ndirecn out 



Relds: 
handlii 
aspect 
attrihde<cr 

dntiffiir 

extref 



Handle as obtained from the last call to HandleGet or NULL 
Aspect as returned from the last call to HandleGet or NULL 
Attriimie Descriptor as returned form AttribDescrCet call. 
Opaque Pointer as returned from AspectCetCail. 
Pointer to structure, where to store the string references. 
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rttums 



ORM.ENoError (Null) if conversion was successful!, else a valid 
ORM Error return code. 



3.1.28 Function Type ORM.AUributeStringToNativeFunc 

This function converts an ORM.Sihng value for an attribute into the applications native 
ra7uo"As*°"'tC^lV° stnicture (da taptr) obtained by a 

Declaration: 



■C=^M_A-:t ribiJteStrincToKativerunc) { 
: J^,y_Ac sue 'cr.Z<- f £ specc . / • 



1.1 •/ 
in •/ 
m • / 



5 c rvalue 



'e-:- cut 



1 ; 



Fields: 



handle 

nspcct 

nltnluii'ncr 

dataptr 

strvalui* 

ret tints 



Handle as obtained from the last call to HandleGet or NULL 
Aspect as returned from the last call to HandleGet or NULL 
Attnbutt* Descriptor as returned form AttribDescrCet call. 
Opaque Pointer as returned from AspectGetCalL ' 
New value as a C-String (ascii). 

ORM^EN'oError (Null) if conversion was successfull. else a valid 
OR.Vl Error return code. 



ize 



3.1,29 Structure ORM_AttributeFuncDef 

This structure bundles tiie attribute related functions for passing to Contextlnitial 
Declaration: 

typedec* struct *:?>:_At t rii-t ef uncTag i 

OFwM_Artrlbi;:e£trin;j:o:;icivuFunc sttingv:onax.ive: 
•:p>i_AcicicuieNariveTci:cringF'jnc nativecoacring; 

>P.:-1_Att rir::t£j.Si*- i v.!;T'^:r:f jFurc inf ct cs tring: 

3.L30 Structure ORM_ContextDef 

This is an internal structure to ORM and opaque to the application layer. It stores the 
function pointers and the information of the root node. 

Note: This structure find the related procedure definitions may change 
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authfuncs Pointer to list of authentication related functions or NfULL if no 

application specific authentication is needed. 

noifound N'o description 

3.1.32 ORM.ContextRelease 

Release .in Applicniion Context. 
Prototype: 

CKM^Ccn-extr.elea *e ( CP.M_Crr.- ex::Sef conczt) ; 
Parameters: 

conixt Pointer to application context as obtained from 

ORM.Contextlnitialize 

3.1.33 ORM.DoRequest 

This hjnction calls the protocol layer to parse an ORM request received and act on it 
accordingly via upcails to functions in the application context, i.e. this is the function to 
be dispatched, when ORM requests are received on a server port. 

Prototype: 

.. tt . . . . w # 

Paranrteters: 
appcixt 

CtliktM 

rcqlen 



The application context reference as returned from 
ORM^Conlextlnitialize. 

An arbitrary call context (reference) maintained by the application 
layer and passed to the authentication, node and handle upcails. 

Pointer to received ORM request 

Length of request buffer in bytes 

Pointer to allocated response buffer 
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maxresp Reference to maximum response buffer length in bytes, on return 

points to number of bytes used in response buffer 
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3-2 ORM Node Layer 

This section was generated from <stdin> by'CDOC on Fri Jan 27 19:59:34 1995. 

The ORM .\ode layer adds another level o( ORM application/ server support, as it actu- 
ally mnininins 3 tree structure to access the application level datastructures. 

This level is accessed from the application/server level via the ORM^Node,.. functions to 
actually build/destroy the tree of objects, components and attributes. 

On the other side it is called from the protocol level and frees up the application to pro- 
vide the appropriate functions for navigation and name space/entity management itself. 

3.2.1 Application Handles 

The nodes of t lie node layer provide a tree structured view to application/ server level 
data, but tho\ ^usually ) do not contain the actual data. A link to the actual instances of 
application le\ ei data is matntained by handles and aspects. Both are opaque to the ORM- 
Node level but *ire interpreted at the layer on top of ORM-Node. Typically the handle is t 
pointer to some application level instance, and the aspect is a pointer, index or type iden- 
tifier, which identifies the type of the instance 

3.2.2 The ORM.Node Structure 

Instances of this structure maintain the tree of virtual components, objects and attributes 

Every node has n tuune and a type, identifying the three different entity types; Object, 
Con\ponciu Atiribute. Object and Attribute nodes are leaf nodes, e.g. they can't have 
children. 

In addition, every node has a parent and a next pointer, to link the actual tree structure. 
Only component nodes have a pointer to the list of children. 

Object Nodes have an additional attribute, called the Link (or Link*Info which usually is 
a stringified NOR). 

Attribute Nodes reference a single attribute by, which is characterize by additional infor- 
mation like* 

• a value type, which describes the kind of value e.g. integer (different sizes), real 
(sizes!), string, shty^k'-sclection or multiple choice 

• a value mode, specifying this attribute as read-only read-write, write-only or persist- 
ant. 

• hints section, which contains additional information for use by the user-interface crea- 
tor, e.g. valid ranges for this value and a unit string. Both values are optional. 

The nodes provide a tree structured view to application/ server level data, but they (usu- 
ally) do not contain the actual data. 
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3,2,3 Struct NodeDef 

Declaration: 



char •naxe; 
struct 0KK_N3deTag •carenc; 

CRM AcsAacec^ref 



handle; 



» * • 



. .*.* icc r j j • : i rat ; 

' - . t: r ; 

» • 4 « * 

I a-^rib; 

^.r, r'.:cc J 

•link; 
f * L * e :: c : 

1 ':::<y. Mcci*?:;.??; 



Field; 



type 

M 

name 
parent 

next 

handle 

aspect 

u.comp 

u.LOmp,f}r>t 

u.compMi^t 

uMttrib.dcscr 



indentities the type of entity, this node describes, i.e. 
ORM_ModeType{Object, Component Attribute. Unkhownl 

Internal use 

The name of the node (object, component or attribute name 

pointer to the parent in the tree, NUL for the root of the tree. 

pointer to next sibbling in chain. This defines the order in which 
niKles of a given type appear in the response 

an opaque pointer for use by the upper layers 

another opaque identifier for use by the upper layers 

union variant for component nodes 

pointer to first child of this component node 

pointer to last child of this component node 

union variant for attribute nodes 

opaque pointer for use by upper layers 
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u.objectJink pointer to stringified link-address of this object (NOR), e.g. the 

hypiriink 

3J1A ORM.NodeCreate 

Creates a new unlinked node. Usually only used by convenience functions and to create 
the root node. 

Prototype: 
Parameters: 



The name of this node (for navigation) 

The type of this node. This type also determines which functions - 
can be applied to this node later on. 

3.2.5 ORM.NodeDelele 

Deletes the given node and all its children e.g. retun\s the space allocated Note: if the 
nodes parent pointer is not NULL the node will not be deleted. - 

Prototype: 

j — ^ 

I ; 

Parameters: 

node The node (and the subtree) to delete 

3.2.6 ORM.NodcAltach 

Attaches a node (and its subtree) into an existing tree as a new subtree. Every node (sub- 
tree) is in at most 1 tree! 

Prototype: 

N r ?.e A c : a r .-. \ 'r>\ HeliiiianDei reiation. /• in '/ 

CP.M^NcdeOeC relative, /■ in •/ 

ll-^j-i NcceD€t subtree /• in 

i 

Parameters: 



•fO-i^S*: ri.-'.q naaie. /• in •/ 

-:?>* Ncae7yceC-ef type /• in •/ 



name 
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relation : Rag either ORM.NodeStbbling or ORM.NodeChlld, specifying 

the role of the relative node, e.g. its a sibbling or its the parent of the 
subtree to attach. If its a parent, the new node will be attached at 
the end of all children, if its a sibbling, it will be placed right before 
this child. 

rcintiiY : an existing node, either parent of sibbling 

itihtrt;^ No description 

3.2.7 ORM.NodeDetach 

Detaches a subtree from the current root tree. This c .vays has to be called, before a sub- 
tree is actually deallocated. The subtree may also be reattached in the same tree again 
after this call 

Prototype: 

- " « 

*>. r. .* • N e .* <'iLzr.isii .' ' in * / 

No parameter descriptions are available. 

3.2.8 ORM_NodeHandieSet 

Sets the handle in the given node (see also ORM_Node<convenience functions>) 
Prototype: 

Parameters: 

node Reference to node structure of any type. 

hnndL' Reference to opaque handle. 

3.2.9 ORM_NodeHandIeGct 

Retrieves the handle from a given node 

Prototype: 

inz 

ZPZA^y,c.r.n':i'*(.:i^iiT3iiT ( Cr-M_NoieO€f node, 

Ac:oH&r\dieDet * handle 

i ; 

No parameter descriptions are available. 



/* 1.- •/ 

/• in «/ 



/• in 

/ • out ■ / 



48 



wo 98/02831 



PCT/US97/1 1885 



32.10 ORM.NodeAspectSet 

Sets ihe aspect in the «i ven node (set? also OKM.Node<convenience hinctions>) 
Prototype: 

***** 

CM Sc<ieAsp«ct:J:ec( ORMJJcceDef -o^«. ^ 

CR.M_AcpAspeccDe£ aspect /• in «/ 

Parameters: 

Reference to node structure of any valid node type. 
Reference lo opaque aspect description. 

3.2.11 ORM.NodeAspectGet 
Retrieves the aspect from a given node 
Prototype: 



/ * in 

r--Y i 5 ceciDef •aspect /* '^^^ 



No parameter descriptions are available. 

32,12 ORM.NodeAttributeDescrSet 

Sets the attribute description of an attribute node 

Prototype: 

:a>! AccAztribCescrDef ate r it 

) : 

Parameters: 

noifff Reference to node structure of type Attribute. 

atirib Reference to opaque attribute description 

3.2.13 ORM.NodeAtlribuleDescrGet 
Gets the attribute description of an attribute node 
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Prototype: 

'?M^AppAtt ribOesc rDef 

No parnmeter descriptions are available. 

3.2.14 ORM.NodeObjectLinkSet 
Sets the link of an object node 
Prototype: 

* • • w 

C r .V _ -Tt^iC i: : : r. i : . < i e ( ^^^^de D e f n >i.e, 

Z P>!_ o t r i r.g I i n < 

Parameters: 

Reference to node structure of type Object. 
Stringii'ied version of the address/nor to call this object 

3.2.15 ORM_NodeObjectLinkGet 
Gets the linkaddress of an object ntxie 
Prototype: 

I r.z 

No parameter descriptions are available. 
3JI.16 ORM_NodeObjectAdd 

for an explanations of parninters, see above. Return created node if operation succeeded 
else \L LL 



node, /•in 
•a^trib /• ouc 



/ ■ in • / 
/. • in « / 



/ • in • / 
/ • cut • ^ 
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Prototype: . 



CRM_Nodepe£ 
•:PM_3cring 

CrwM String 



N'o parameter descriptions are available. 

3.2.17 ORM^NodeComponentAdd 

Prototype: 



C IOl_Re iacionCef 

CKM_N>icOcf 

0PM_3cring 

7:-.M_AppKaadie2ef 

:;c<_ApcA3?ecL2ef 



No parameter descriptions are available. 

3il8 ORM.NodeAttributeAdd 
Prototype: 



relaclor, 

relative, 

nasie, 

^iandXe« 

a^pect^ 

lirticadcr 



rexatiopw 
relative, 
name, 
handle , 
aspisct 



/• 
/• 

/• 
/ • 

i 



In •/ 
in «/ 
in •/ 
in •/ 
in •/ 
in •/ 





in 


-/ 




in 


•/ 


/• 


in 




• 


in 


•A 




in 


- / 

4 



C t de A r - r 1 r u :*e A :* ; c K:-! i a t i snUe f r e 1 a t i c r. 



No parameter descriptions are available. 



/• in •/ 



'Le>* icrinq name* ^* 

:PH~AopKandleDef nandl^. in •/ 

AppAapectSef aspect, 3-^ / 

CKM^AppAttritoSescrOef attribdeflcr in •/ 
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3.3 ORM Aspect Layer 

This section was- generated from <stdin> byCEXX on Sun Jan 29 17.-00:Sl 1995. 

The ORM aspect layer adds another level of ORM application /server support on top of 
the ORM Node/ Handle layer, and supports the retrieval and modification of aspects i e 
groups of nttributeS'from or into application dau structures, once those have been recis- 
lereti with this layer. ^ 

This level has no additional (down-call) hjnctions but defines data structures to be pro- 
vided by the application layer. These are then accessed/used by the aspect upcaU func- 
tions, if those have been registered with the ORM protocol layer. 

The Aspect layer implementation of the ORM-SSL works as follows: 

On Aspt?ciOIICet requests, just a pointer is returned which points at offset bytes (as set 
in the Aspect descriptor) from the beginning of the handle. On AspectCalllnit calls, a copy 
of the aspect, e i;. size bytes from the area pointed to by handle, starting from offset, is 
taken into a private memory area. This copy is then passed to the Attribute conversion 
routines to write the new values into. On AspectCallSet calls, the application level set 
function as denoted by the aspect descriptor is called and the private copy (request struc- 
ture) is released afterward. 



3,3,1 Function Type ORM^AspeclSetFunc 

This function is called from the aspect layer to actually apply the new attribute values to 
the application layer and/or initiate the requested state changes. This function usually 
should not block, e.g. should not wait until the initiated stale change is completed. Any 
kind Of intern\e».iiaie slate should instead be visible to a client on request (i e not 
STOPPED -> STARTED, but STOPPED -> STARTING -> STARTED, if starting implies a 
/i<!flt»iVr operation. ' 

Declaration: 









/• 


in 






_«\ ' I -a c T. :'. .< • r r. t a - f 


^. spect. 




in 


•/' 






request. 


/ • 


i.n 




■ • ■ • 

* 1 


I, a r 1 1- l r *? : 


jucccnc , 


« 


i.n 


•/ 


^ ^ •J 


WW * K . • Id 


•ecrortezt 




out 





) ; 

Fields: 

^^ndte the handle as returned from HandleCet 

"^^Pt'i-V Reference to the aspeadescr.^ 

^^py «^ the aspect as described by the aspecidescr updated with 
new values. 
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current Reference to aspect within handle 

crrortcxt Where to Store a point r to a short textual description if the 

requested values could NOT be applied. 

returns ORM.ENo Error if all new values could be applied^ or 

ORM.EParameterList if paremter set is inconsistent or 
ORMlEMissing Attribute if a niandatory attribute is NULL 

3-3.2 The ORM.AspcctDescrDef 

This descriptor maintains infomwtion about the application data structure (usually refer- 
ences by the ORM_AppHandle) or parts of it. It describes the binary size, the offset 
within the handle, and contains pointers to functions to actually retrieve or modify this 
aspect of the application instance. 

Note: It is currently open, whether there should be a procedural interface to set up the 
aspect descriptor instead of providing a structure type definition to be passed initialized 
by the application code. 

[Declaration: 

c y t T .^l^-:: :.Zti.i : t Tag \ 

'name; 

. z-r : size; 

I :r»a aopid; 
) O RW_A 5 pe c - Oe i c r De f ; 

*. 

Fields: 

name Pointer to name strings for identitication mainly. 

Offset The offset in bytes within the instance, where this aspect starts. 

This usuallv is the offset of a sub structure in the instance. 

size The size in bytes of the instance, the application handle pointer 

points to. For set-requests, the container for the new value is cre- 
ated by copying the handle, and inserting the new values in it. 

fla^ [f set to ORM.AspectGetlndirect. the offset indicates the offset to a 

pointer, pointing to another structure of the above size. 

ictt Pointer to function, which is called to apply (a set of) new values to 

an application instance. 

appext any value of pointer size the application wants to store with the 

aspect. This may be used to store a create.aspect function pointer. 

appid Opaque identifier, which may be used by the applications layer 
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3.4 ORM Attribute Layer 

This section was generated from <stdm> by CDOC on Fri Jan 27 19:59:34 1995. 

The ORM Attribute layer adds another level^ of ORM application/server support on top 
of the ORM node layer, by providing (list of) attribute descriptors, which simply initial- 
ized by the application code, nilowe automatic conversion and generation of the attribute 
meta information, requested by the ORM protocol layer. 

The implementation of the attribute layer in the ORM SSL assumes, that it is converting 
to and from a binary blob of data, identified by the (lower level) aspect descriptor The 
goal of this layer is to reduce the coding effort needed by the application writer at this 
layer, just to provide some initialized descriptors and pass them to the ORM SSL via sin- 
gle calls per every instance created. 

3.4.1 The ORM.AltribuleDescriptorDef 

This dat*i stnicuiro describes .i single attribute, e.g. its native type and mode, its size, 
pointers to cun\ ersicm functions Iti addition it maintains hooks for preset mela-info like - 
Unit and R/(«v'i'. 

Declaration: 

zype^^z scr-rc :PJ<_Att ricu^eOescrTag { 

■Z RM_5 i r i r.g name ; 

•:pm_ At'iricryreP^f datatype; 

vr^:- 5-r:--r ranee; 

' offset; 
• ■ aize; 
■ •'^''^ .. '■ i " - r : :-j I i. v -= : i i r i ngf unc n a t i ve c o a t r i.-ig ; 
'^rOI^T ;r.v«rr,i!:'.-3t c L.-:gToNai.xveFunc stringronacive: 
C r>t_AcpCcr. ve r te r Ar^Se t ccnva rg ; 

I 0?i<_A-trifcuteDesccDef ; 

Fields: 

The name of the attribute. 

Jj/iiiy/ii' 1 lie i> pe of data of this attribute (ORM.AttributeTypeDeO. This is 

a superset of the data types, the ORM protocol defines and used to 
determine implicit conversion routines. 

'"txfe The allowed access modes of this attribute out of 

ORM.AttribMode values, e.g. read-only, write- only, read-write. 

^^"S*^ A string describing the allowed ranges for new values for read- 

write or write-only attributes only. This is a ORM hint, and as such 
optional 

A unit string (usually ms, Mb, etc.) which may be used by object 
specific user interface generators in any way and by default if 
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present is placed behind the attribute value. This is also an ORM 
hint and as such optional. 

conversion funciion A function pointer to an application specific conversion function. 

to convert between native and ORM presentations. Nate: This is 
not lo be confused with the similar functions of the ORM.Coniext 
structure. For the <conversion-functior\> to be called, the 
ORM.Node.conversions functions have to be setup in the 
ORM.Context. 

conversion tirg An opaque pointer to any argument, the conversion function may 

need to convert this attribute. 



3.4.2 ORM.AttributeOeate 

This ainction combines several actions required to register an attribute of a (new) 
instance wit h ilie ORM SSL i.e. it creates an attribute node under "the given parent (which 
must be of OR.M_NodeTypeComponent) and attaches the attribute description and the 
handle information to it. 

Prototype: 



: ? M_ A c t: r i c u :.e 3 - f Lis t De I 

1 ; 



relative, / " 
re lac ion, /' 
ac cfic-aeact , / * 



Ln •/ 
in - / 
in •/ 



asoect^lescr, / • in •/ 
handle « in ■/ 



•r.ew 



/ • out 



« t 



Parameters: 



relation 



atlribiii*<i<:r 
handic 



pointer to relative node. If relatian is set ORM.NodebParent then 
this has to be a node of ORM_NodeTypeComponent. If relation is 
set to ORM.NtxieisSibbling, then this node can be of any valid 
node type. 

Either ORM_NodelsParent, if the node relative should be the par- 
ent of the new attribute node, or ORM.NodelsSibbling, if the new 
attribute node should be inserted after the relative node as a sib- 
bllng. 

\'o description " ' 
No description 

Pointer to (he application instance this attribute belongs to or 
ORM.Handlelnherii (-1), if the handle should be taken from the , 
parent (or its parent and so on). 



Pointer to new attribute node or NULL on failure. 
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3.4.3 ORM.AuributeDestroy 

This function detaches the attribute node from the tree of nodes if any, deletes the node 
structure and deletes any depending stmctures, i.e. the attribute descriptor. 

In the current implementation this function* maps direaly to ORM_NodeDestroy, but 
nevertheless this function should be calied for attribute nodes created with functions of 
this layer to be able to deallocate any dynamic memory. 

Prototype: 

inc 

Parameters: 

attrnade Pointer to attrbute node. 

3.4.4 ORM.AttributeListCreate 

This is another convenience functions to add a list of attributes to a component. The 
given node must be a of component type and is used as the parent for the new list of 
attributes ( which is appended to the end of the list of child-nodes). The pointer to the 
attribute descriptor now points to an array of those descriptors, where the end of the 
array is marked by a descriptor whose name pointer is ^fULL 

Prototype: 
i r.t 

.. r^t^N - -^pjC^o £ pacenc, /• in «/ 

:?.-._A=pHar.ile£e: handle, /• in •/ 

■ > :<^k -c : : Tc* o r f a S(5ect iesc r , /'in*/ 

w.":i_AciiiCwZ4t:;e3ir LiscDef attrdeacriiat , / in •/ 

dttrccunt /■ in •/ 



Parameters: 
parent 

handU 



attrdcscrlm 



Pointer to an existing component node, who is the parent node of 
all newly created attribute nodes. 

Pointer to the application instance^ all attribute belongs to or 
ORM^Handlelnherit (-1), which indicates, that the actual handle is 
detennined by the parent (which again may have its handle set to 
ORM.Handlelnherit!) 

No description 

Pointer to an array of ORM.AttributeDescr, with name^NULL in 
the last element if attrcount is < 0. 
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attrcoutit The number of attribute descriptors in the list or the number of ini- 

tial attributes from this list to attach to this node or if the end of 
the list (array) should be determined by a NULLnodeinfo pointer. 
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3.5 ORM Attribute Conversion Support 

This section was generated from <stdin> by CDOC on Sun Jan 29 18:13:38 1995. 

This part or the ORM Server Support Layer provides functions for converting generic 
ORM data types between their native (binary) and the ORM (ASCII) presentation. The 
interface between the attribute and the conversion layer is defined by to hanction types, 
one for converting application native data into an ORM representation, one to convert 
ORM attribute value strings into the applications native presentatioa Beside the conver- 
sion functions provided by the ORM-SSU every application may provide its own special 
converters as long as their interfaces conform these function types. 

3.5.1 Function Type ORM.ConverterNativeToString 

This hinction ts called to convert a single native value into its string representation. In 
addition lo the value siring it nw y generate the range and unit strings, if the pointer val- 
ues passed are non-null. If the converter function returns NULL in these pointers, the 
lower (attribute) layer may provide default strings if any. 

Memory Allocation: The memory to hold the converted string value{s} has to be provided 
by the converter function. It is reasonable to use static memory for this purpose, t)ecause 
before the converter function is called again, the ORM protocol layer will copy the strings 
returned. 

Declaration: 



" r .H _A (3 0 d r. 1 P n ly o f p t r , 

C km^Ap. t r iiut e^=5c rLi :3tDe t datatype 
OPM_A?pConve c ce r ArgO^ f ccnva eg, 
CRM_3trin*7 -St rvalue, 

CM_St ring •strrange, 
Of .M_ 3 r. r i r.g • 3 1 r un i t 



/• in •/ 

/• in •/ 

/• in -/ 

/• in •/ 

out •/ 

/• out •/ 

/• out •/ 



Fields: 
ptr 
size 

datatype 



itwiihti' 
strrange 



Address of native data element (e.g. attribute value) 
Bvte-sizeof data element 

One of the ORM^AttributeTypes identifying the type of the native 
data element and its mapping to an ORM Protocol data type (??is 
this overloaded ??) 

Any kind of argument (pointer) for this converter (as provided 
with the attribute descriptor for ex.) 

Where to store the pointer to the converted value string. 

Where to store the reference to the optional range string. 
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itruntt 



Where to store the reference to the optional unit string. 



3-S.2 Function Type ORM.ConverterStringToNative 

This funaion is called to convert a single ORM string value into its native presentation. 
The pointer for the result usually points into a set of different attributes, e.g. an aspect, 
which usually is a (partial) copy of some application data instance. 

Memory Allocation: The destination pointer provided references some valid memory (e.g. 
an aspect), but for references (the native value is a C-string for ex), there is usually not 
enough space for the referenced value. This space must be allocated/provided by the 
converter itself. It is legal, to reference the original string as passed in to the converter 
function, but then the AspectCallSet function should make a copy, if the string is needed 
beyond this call. 

Declaration: 



,/pede: rPM^Sci-.us (• OR^t^CcwercecSccir.gTcNaciveFunc) ( 



? :•! A t : r r ry t: c D e 5 
- y pCc n V e ri. e i A cgOe f 

1 : 



size, 
datatype, 
ccnvcrg, 
St rvalue 



/" in 

/ • in 

/• in 

/• in 



* 

• / 
•/ 



Fields: 
dest 

mnxsize 
iiatatypi' 

itrvalue 
retums 



Address /destination of native data element (e.g. attribute value) 
Maximum byte-size of data element 

One of the ORM^AttributeTypes identifying the type of the native 
data element < 

Any kind of data (pointer) for this converter as provided with the 
attribute descriptor 

The new attribute value in its ascii presentation. 

ORM.ENoError if conversion was successful! and the resulting 
attribute value is valid or ORM.ERangeError. 



3.5.3 ORM Built (n Conversion Functions 

The follow in^ functions are provided to convert generic C datatypes between their ORM 
and their native presentation. In addition sub functions are provided to support the spe- 
cial ORM SELECT and MCHOICE types, which are called by the generic converters. 
Along with these sets two new data structure (types) are introduced. 
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3,5.4 Fundi n ORM.GcnericNativcToString 

This function converts standard C-data types into their ASCII presentation. It returns 
onlv the converted value, but does not support the range and unit parts (e.g. returns 
NULL for those, ft requested). In case of SELECT or MCHOICE functions, this fur^ction 
calls the related ORiVl .Select- orORM.MChoice functions. 

Note- It is currently open, whether the conversion argument convarg may be used to spec- 
ify a format string a la printf. Furthermore it is currently open, whether a isfULL conver- 
sion function in the attribute descriptor should be directed to this (default) hinction. 

Arguments as for OR.VI.ConverterNativeToString! 
Prototype: 

CKM_iI c ^ .:?-X.ri^r.e : i. zt: i i ve T i S t r i ng ( 
CRM_Att -ibTvpeDez 

No porametcr descriptions ore avnilable. 

3.5,5 Function ORM.GenericStringToNalive 

This function converts ASCII C-strings into standard C-datatypes. In case of SELECT or 
MCHOICE functions, this hmction calls the related ORM.Select.. orORM.MChoice 
functions. 

Note: It is currently open, whether the conversion argument convarg may be used to spec- 
ify a formal string a la acanf. Furthermore it is currently open, whether a NULL conver- 
sion hinction in the attribute descriptor should be directed to this (default) function. 

Arguments as for ORM.ConverterStringToNative* 



ptr. 


* 


in ■ 


t 

/ 




/- 


i.T ■ 


/ 

t 




/■ 


in • 


/ 


ccnvacg. 


/' 


ia • 


4 

t 


« scrvalue. 


/ ■ 


out 


•/ 


■ range value,. 


/ ■ 


ouc 


•/ 




/ • 


cue 


•/ 



Prototype: 

CRM^Sca-us C?;.X_.7*fner icSi ri noToNative ( 
" CnM_Acp05caPcrO«c ptr, 

size iraxaize. 



in •/ 



/• in •/ 



rPM^AtcticryceCftf type, /* 

- oy" f, :: :» r. ve r t o r A r ^ De f .rr^n v a rg , /'in"/ 

•Tvi at rvalue /* * i'* *^ 



» 



No parameter descriptions are available. 
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3.5.6 Structure ORM.StringMapDef 

This type of structure is used to niap strings to binary values and vice versa. It may be 
used to convert internal flags and states to friendly names. SiringMaps must be termi- 
nated by an entry with name set to NTJLL * 

Declaration: 

:vr-eclef Jirv.ct C?^M 3t rir.rjS.apTag I 

Fields: 

name Friendly name for this key. 

key The binary native value of the key 

3.5.7 ORM.StringMapToString 

This hjnction nvips a vnlue key to a string using the given SlringMap. It returns the string 
of that nvip emr\, u hosc' key is ev^ual to the given key, else it returns the string passed in 
notfiiurui. 

Prototype: 

C c r t r. a :^ ft c r r J c r i r.*? i V iO*_S t r i n^.^ipDe f ma p , 

"?:^_:•^ey key, 

Serine r.ci round) ; 

Parameters. 

ff«</* Pointer to a sequence of map entries 

key Binary key value. 

noifound string to give back, if none of the keys in the map matched. 



3.5.8 ORM.StringMapToKcy 

This function maps a string value to a binary key using the given StringMap. It returns 
the key of that map entry, whose string is equal to the given key, else it returns the key 
passed \v\tiiXH\i idkiy 

Prototype: .... .. 

CR.M_Kev 

C R.M_ ; r r 1. g>tii p T f .r ^ y ( C ?.M_ 3 1 r i ngMapCe f rr-s p , 

w?:M_.Kt:>y invalidicey > ; 

Parameters: 
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map Pointer to a sequence of map entries 

name No description 

invalidkey No description 

3.5.9 Structure ORM,StateMapDef 

This structure is used to map statt^ into strings, where a siaU is assumed to have a distinct 
set of possible next states, depending on the current value. E.g. this structure can be used 
to derive the set of possible new values i.e. it can provide the range value for a state 
attribute. 

Otherwise it is used similar to the simpler StringMap structure. StateMaps must be termi- 
nated by an entry with name set to NULL 

Declaration: 

:>c<r-;ec : r\M_-- : aMapTig \ *' ' r.zz at ^ne U.S. A.:: •/ 

-?0''._: 1 r :. :;g v a 1 ici:ie:< c 5 ; 
; • V r^K^i c 5 1 e Ma pDe f : 

Fields: 

nam^ Friendly name for this key. 

state The binary native value of this stale 

vnliiint'xt> String of comma separated names of next valid states which may 

follow this Slate. 

3.5-10 ORM.SlateMapToString * 

Convert an encoding of a state into a friendly name using the given statemap. If the state 
could not be found, the string passed in notfound is returned. 

Prototype: 

^* K:^ c ;-. : - 3 c : - i ; ; i no i 

CH.M_icring 

Parameters: 



^^P Pointer to a <name=NULL) terminated slate map. 

^tate the binary Slate 

notfound siring lo return, if none of the entries in the map had exactly the 

I'iven Stale kev. 



» L a - -i , 
Ticz found) ; 
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3-5,11 ORM.SlateMapToKey 

Convert a string representation of a state into a native encoding of a state using the given 
itaiemap. If the siring could not be found, the state passed In invaiidstaie is returned. 

Prototype: 



CPC^l_£':3ioXapr?Key ( CR:'1_3i at eMapDcf map, 

CRM Key invalidatace) ; 

Parameters; 

map Pointer to a (name=(^LL) terminated state map. 

name No description 

iniiMstotc No description 

3,5.12 ORM.StateMapNextByKey 

Return the comma separated list of valid next states given the current state. 
Prototype: 

C hyi_^ t i :. <!y.a p: i ^- x 2 y Key ( RM_5 tit eMa pDe £ ma p , 

Parameters. 

map Pointer to a (name=NULL) terminated state map. 

state the binary state 
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3.6 ORM Dump & Restore Support 

This section was generated from <stdin> by CDOC on Fri Jan 27 19:59uJ4 1995. 

This module of the ORM Server Support Library supports the dump and restore of com- 
plete subtrees, and therefore can be used to save the current configuration to a persistaixt 
storage media (i.e. the MSF Warehouse) and reload it from there. The actual 10 funaions 
are currently not supported by this layer or the support library at ail! 

Dump and Restore are functions of the ORM SSL and not of the ORM protocol (i.e. there 
is no DUMP or RESTORE request defined in the protocol). 

This implies, that these functions have to be dispatched out of the application layer 
explicitly. One (intended) v^ay to dispatch those functions interactively is to provide 
pseudo components in every subtree, which should be independent storable/reloadable. 
These contain the required parameters like Warehouse location or version name as 
attnbuies. An Attribute-Set rer.]uest to this subtree then results in the execution of the cor- 
responding runciion. 

Under the layered view of the ORM SSL these two functions belong to the protocol layer, 
as they use (nearly) the same functionality of the higher layers via upcalls. 

3.6.1 General Model: 

Starting from a given node, which is used as the root of the relevant subtree to dump, all 
componeni>. object links and writable attributes with their meta information are recur- 
sivly f xtracied relative to the current subtree root. The extended/meta information on 
the persistent nit^jia can be used to interprete the stored attributes and apply changes to 
the stored version without the ORM server/ application alive but through special clients 
(by an ORM /Warehouse gateway for example). 

The dumped ORM tree can be used to reload the whole subtree at any time, by providing 
the node and call the restore function of the ORM SSL (which is a special kind of Set- 
Request). 

This special kind of SET request creates a new situation, as components (or any new sub- 
tree) may have been created dynamically by the ORM server application on request. On 
the next cold start of the application, these subtrees do not exist. 

This results in failed lookup requests by the ORM protocol layer, which usually is treated 
as an error (remember: ORM-P has no direct support for object/component creation, but 
this is emulated by sets of writeonly attributes in separate subtrees, i.e. New.X To handle 
this case, the application can provide a special function during application context setup 
to create new instances including the ORM subtree (ORM.N(KleNotFoundTrapFuncO). 

A parameter is passed to this creation function, which indicates, whether this situation 
was causevi by a regular ORM protocol request or by an internally generated restore 
request, so the applicniion coi\e can still decide to refuse the creation. 
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3.6.2 ORM^Dump 

This function extracts the ORM entities in the subtree pointed to by subtree into the char- 
acter buffer, so it can be used by a later ORM.Restore function (or can be used as a subre- 
quest in a regular ORM protocol request). 

it is the responsibility of the caller to provide a sufficient buffer, which can hold the sub- 
tree information of the given depth! 

Prototype: 



.:PM_f til- u3 



■ * w ^4 a t. # . 

' — r* " * !Ti3 rc ^ ^ n 



Parameters: 



ii'iuil 



maxlen 



The root of the subtree to dump. All navigation information is 
saved relative to this node. 

The depth, up to which entities in this subtree should be extracted. 
A depth of 0 means, direct childs of the given sub-root only, Le. if 
the subtree points to a component node with an attribute node as 
one of its direct children, the name of ihe'atlribute would be 
extracted, but not the value or other extended attribute informa- 
tion, if depth=0. A depth of -1 extracts the whole subtree, inde 
pendent of its depth. 

is bitmask, defining what kind of entities should be extracted: 
ORM.DumpSetObjects ORM.DumpSetComponents 
ORMDumpSetAltributes ORM_CXimpSetWritable 
ORM"DumpSetDefault = Objects I Components I Writable 
ORMlOumpSetE very Thing = Objects 1 Components! Attributes 

The address of a character buffer, where to store the extraaed 
entity infonnation 

Pointer to the maximum length of this buffer. On return, maxlen 
will contain the number of bytes used in this buffer including the 
C-Strini; AO' terminator. 



3.6.3 ORM.Restore 

Function to reload the saved ORM information into an existing subtree, where at least the 
root of the given subtree has to exist. Note: Because the restore request may fail som 
attribute modificatioi^s aireadv performed, an application may want to call ORM.Uump 
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(int at mporary buffer) before actually calling ORM.Restore, to be ablet undoth. 
tial operations. a - «naotne 

Prototype: 



Parameters: 
subtree 
buffer 



^rjvi * , - .. 

J ; 



-At subixee, 
bu£f e c, 
• length 



Node of the subtree to load the management information into, 
pointer to ORM subrequest sequence. 

pointer lo length of the request. On return, this will contain the 
number of bytes processed from this request. 
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3 J ORM SSL Generic Datatypes 

flifndef _ORM_TlfPE_H 
# define 2obm~TYPe"h 

/« 

■ Some generic def ir.iiisr.s. may become obsolete 

c y pe de f e r. 'j.t. • 
Tr'je 

! Ccciein; 

fifndef KULL 
♦define NULL (void 
#endif 

typedef \:ns icned isng aize^t; 

»-:le f ir.e C=,y_rt r ( ::f3e',) (void •j(t3ize_c ) (base) + (size t)(off3et)) 

« re : *, r. : ?.V y ^ 1 : r . :< j w - : i • ) rr.a i 1 oc ( x ) 
tfdefir.e I R.y_r re-e :-: i rreetx) 

/■ 

■ T.ore CRM seen : ic scuff 
•/ 

/• 

• How requests and responses are passed to the ORM protocol layer 
•/ 

typedef rr.ar 'ORM_ReqT:estOef ; 
tyce*e: ,T.ar • *RM_Sespo- seDef ; 
/ - 

• The principal type of every ORM protocol entity, e.g. names and values, 

• but also used T.cst C-strir.gs. 
. «/ 

typedef char •ORM^String: 
/• 

• Used tzz SiateMaps and Spring Maps as the lookup key 
type Jet* l-ng :?M_Key; 

/• 

' The following are various opaque handles. Opaque mainly to the protocol 

• layer but also for the lower of two stacked layers. 

typedef void •CRM_AppNodeOef ; 

typedef void 'CRM^AppHandleOef ; 

typedef vc;2 • :.^_AppA3cectDe f ; 

typecs: v,:,: • : .^M^AppSataPt cOef ; 
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-ypedef voii 
typedef void 
cypedef vcid 



/ 



•CRM_AppAtcribOe3CrO«f ; 
'CPx^AppCailConcexcDef; 
• 0 PX^AppC r r. V e r t e c A r gDc f ; 



Valid Arce*3 5 mccea fcr 



an attribute 



typedef er.-j.r. ; 

:.HM_A: ; ncMcdeNone, 
CR«_A: : ritMcdeP.w, 

ORM_A 1 1 r i b Mode wo , 
CR.M_Att ricModeRWp 
) CRM_ A 1 1 r i bModeOe f ; 



• Known macivei datatypes, which a 



re supported by the Generic conv«rt«j 



tycedef e: 

CKM_A' 
CrJ^ A' 



A 



CRM^Att : 
CR.M_At 1 1 
OR-M~Attr 

ray.^At'.r 

CRM^A- - r 
ORM^At t r 
CR.M~At t r 

3n>!~Aiir 
C?.^"At t r 
•» « ^ «, 
ORW^-^tzr 
ORM^Actr 
} OR.M At 



*»c»/ize*rit«/ 

r - c . y p 5 - r. t - , 
rii:rype'j:r.t2, 
ri!:Tyce:r.t4 , 
ricTyce'JInt^ , 
rlcTycelr.ta, 
icTyce, IntS, 
ii:Type.^eal32, 
ibTyceReai64, 
: = Typeit ring, 
:-Tyc^:-e>::ci , 
ir:Typeieiect. 
icTyceSt ace, 
ibTypeOpticr., 
ibTyceMChoice, 
ibTypeUnlcnown 
t ribTypeOef ; 



/ * *. out of mAny •/ 

/• 1 cut of many, but with dynamic range 

/• binary switch ON/OfF rss/NO */ 

/ ' n out of many •/ 



CRM crrcr Ccd 



cr .c^es, used as well by the protocol as by the ORM SSL 



typedef er.*-n • 
RH_tNc £ r r ? r , 
ORM^EPe cmiasicr., 
Oft«_ENo S uc h.Ncde , 

ORM^ENoScchAt t ribute, 
ORM^ENc S u c hO b j e c c , 

ORM^Elnval idOperat ion, 
ORM^EProtOCol , 

CRM_ECcwnur.ica 1 1 cn , 
CRM_ERar.ge. 

ORM^EP.arameter List , 
05^w_E:jc5pare, 



Operation successful! ! •/ 
None or wrong auth. information '/ 
some narae in pathname could not be found •/ 
Attribute in Set-Request doesn't exist •/ 
Object/Manager could not be found •/ 
Operation not applicable to node type */ 
ORM protocol violation •/ 
lower level corom error •/ 
new attribute value out of range •/ 
set of attributes not applicable •/ 
mandatory attrib. missing or MULL •/ 
internal allocation •/ 
response buffer ■/ 
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ORM Eincernai, / ' ORM Internai error -> bug •/ 

CRM^EApplicacicn, appiicaci-on Level error -> bug •/ 

1 CRM Scacua; 



• Tvpes :i r.zzes ir. z^.e virt-al tree. Noce, that only nodes of cype 

• C?v._r):^5T/?e::rrp:r.er.; zsr. r.ave cniidreni 

■/ 

typedef enum ( 

CRM NodeTypeUnitnown, 
CRM^NodeTypeOb ject, 
CR«2-^'cdery peCcnponent , 
OR>t_NcdeType Ac tribute, 
CRM^rJcdeTypeAry 
• CRM_SrcleTvpeCef ; 

/ • 

• Tvcei ti Z?y. icq,c3i3. Ncie ir.ac the Dump and Reacore requesta ace 

• kzz ci"z 7i ir.^ pzzizzci, cue only available wlchin the ORM 

• server support library 
•/ 

i 



typedef enum 

C -^M^Req-j estCbjeccGet, 
CRM^RequescCoxponentGec , 
CRM~Req-:estAc- r icuteGet . 
;?M Be rce^tAtt r:.i;utelr: f oGet , 
;?>:"?■= r-- :- 5: A:-. : ;c jceie^. 
rP-M^rie Set , 

;RM_?.eq ^est Zet , 
C r>!_=^eque s t Du.-np . 
C R«3-^^ que s c Re 3 1 o re 
I ORM^RequestTypeCef ; 



tendi f 
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WHAT IS CLAIMED IS: 

1. A system for managing objects, including a first server, comprising: 
a first receiver portion configured to receive a request in a 
hypermedia format; 

a first translator portion configured to convert the hypermedia 
request to an object request; 

a sender portion configured to send the object request to an object 

manager; 

a second receiver portion configured to receive a response from 
the object manager; and 

a second translator portion configured to convert the object 
manager response to the hypermedia format. 

2. The system of claim 1, further comprising a second server, including: 
a third receiver portion configured to receive a request in a 
hypermedia format; 

a third translator portion configured to convert the hypermedia 
request to an object request; 

a second sender portion configured to send the object request to 
an object manager; i 

a fourth receiver portion configured to receive a response from the 
object manager; and 

a fourth translator portion configured to convert the object 
manager response to the hypermedia format. 

3. The system of claim 1, further comprising: 

a second sending portion configured to send the hypermedia 
format data from the sender portion to a browser to be displayed. 

4. The system of claim 1 , where the object manager manages a self- 
describing object. 

5. The system of claim 1 . where the object manager manages a non-self 
describing object. 
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6. The system of claim 5, where the object manager performs a "worm" 
function. 

7. A method for browsing objects, where a browser communicates with 
a server, comprising the steps, performed by the browser, of: 

sending an initial URL to the server; 

receiving first data from the server, where the first data specifies 
an object corresponding to the URL; 

sending user-entered data associated with the object to the server; 

and 

receiving second data from the server, where the second data 
specifies a second object corresponding to the user-entered data. 

8. The method of claim 7, 

wherein the step of sending an initial URL to the server comprises 
the step of sending an initial URL known to the browser, where the URL is the 
URL of the server. 

9. The method of claim 7, 

wherein the step of sending an initial URL to the server comprises 
the step of sending an initial URL entered by the user, where the URL is the URL 
of the server. » 

10. The method of claim 7, 

wherein the step of sending user-entered data associated with the 
object to the server includes the step of indicating a "set" operation in the user- 
entered data. 

1 1. The method of claim 7, 

wherein the step of sending user-entered data associated with the 
object to the server includes the step of indicating a "get" operation in the user- 
entered data. 

1 2. The method of claim 7, wherein the step of receiving second data 
from the server includes the step of receiving data corresponding to an attribute 
value of the object. 
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1 3. The method of claim 7, wherein the step of receiving second data 
from the server includes the step of receiving data corresponding to a second 
object linked to the first object via an object-link. 

14. A computer program product comprising: 

a computer usable medium having computer readable code 
embodied therein for managing objects, the computer program product 
comprising: 

computer readable program code devices configured to cause a 
computer to effect receiving a request in a hypermedia format; 

computer readable program code devices configured to cause a 
computer to effect converting the hypermedia request to an object request; 

computer readable program code devices configured to cause a 
computer to effect sending the object request to an object manager; 

computer readable program code devices configured to cause a 
computer to effect receiving a response from the object manager; and 

computer readable program code devices configured to cause a 
computer to effect converting the object manager response to a second 
hypermedia format. 

1 5. The computer program product of claim 14, further comprising: 

computer readable program code devices configured to cause a 
computer to effect sending the second hypermedia format data to a browser to 
be displayed. 
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